Composing your own blocks with Blockstudio is extremely easy. The plugin will look for a blockstudio folder within your currently activated theme. Inside, every .php and .twig file will create a new block by making use of the file headers or register variable.


Let's imagine the following blocks are registered using Advanced Custom Fields:

blockstudio -- cta.php -- news.php -- button ---- index.php ---- register.php -- contact ---- index.php ---- newsletter ------ index.php ------ modern.php

The above structure would create 7 different blocks with following block names:

  • acf/cta
  • acf/news
  • acf/button
  • acf/button-register
  • acf/contact
  • acf/contact-newsletter
  • acf/contact-newsletter-modern
Arrow Forward Circle

Unlimited nested folders are allowed.

Every filename can only contain lowercase alphanumeric characters, dashes, underscores and must begin with a letter. The acf namespace is automatically being added by ACF. Metabox would use the meta-box namespace instead.

As you can see, naming your file index.php or index.twig will automatically name the block after the parent folder. Please note that this isn't working in the root folder of your block directory.

blockstudio -- cta.php -- index.php
Alert Circle

In the example above only one block (cta) will be registered since the index.php lies in the root folder.

Naming collisions

Blockstudio automatically gives your blocks unique names depending on their prefix, file name and how deeply they are nested. Since no files can be named the same in a file system, no two block names will ever be the same.

However, using a combination of an index file inside a folder with the same name as a file in the same directory, there is possibility of two blocks having the same name, in which case the file not inside the folder is being preferred since it will be registered first.

blockstudio -- my-block ---- index.php my-block.php
Alert Circle

Both blocks have the same name. my-block.php will be registered as a block.


Blockstudio provides two different methods to add metadata to your blocks:

File headers

<?php // cta.php /* Title: Call to Action Description: Call to action element. Category: blockstudio Icon: lightbulb Mode: preview SupportsAlign: false SupportsMode: false */

The above is equivalent of this ACF code:

add_action( 'acf/init', 'register_cta_block' ); function register_cta_block() { if( function_exists( 'acf_register_block_type' ) ) { register_cta_block( [ ( 'name' => 'cta', 'title' => __('Call to Action'), 'description' => __('Call to action element.'), 'category' => 'blockstudio', 'icon' => 'lightbulb', 'mode' => 'preview', 'supports' => [ ( 'align' => false, 'mode' => false, ], ] ); } }

While both of these examples will register a block, nothing is being rendered yet. Instead of relying on callbacks or templates, markup in Blockstudio is being defined in the same file like so:

<?php // cta.php /* Title: Call to Action Description: Call to action element. Category: blockstudio Icon: lightbulb Mode: preview SupportsMode: false SupportsAlign: false */ ?> <p>Buy my product!</p>

Below is a full list of possible settings that can be set in the file header.

Please note that some block supports need to be activated in the theme, check the Gutenberg docs for reference.

<?php /* Title: Testimonial Description: Content block for customer testimonials. Category: marketing Icon: smiley IconBackground: #000000 IconForeground: #ffffff Keywords: testimonial customer content (space-seperated) Mode: preview Context: side Align: full PostTypes: page post (space-seperated) Parent: acf/my-block SupportsAlign: false or left right full (space-separated) SupportsAlignText: true|false SupportsAlignContent: true|false or matrix SupportsAlignWide: true|false SupportsAnchor: true|false SupportsColor: true|false SupportsColorBackground: true|false SupportsColorDuotone: true|false SupportsColorGradients: true|false SupportsColorLink: true|false SupportsColorText: true|false SupportsCustomClassName: true|false SupportsFullHeight: true|false SupportsHTML: true|false SupportsInserter: true|false SupportsJSX: true|false SupportsLock: true|false SupportsMode: true|false SupportsMultiple: true|false SupportsReusable: true|false SupportsSpacingBlockGap: true|false or horizontal vertical (space-separated) SupportsSpacingMargin: true|false or top right bottom left (space-separated) SupportsSpacingPadding: true|false or top right bottom left (space-separated) SupportsTypographyFontSize: true|false SupportsTypographyLineHeight: true|false */ ?>

It is possible to add additional metadata via PHP while maintaining the data set with the file header using the $settings variable.

<?php // cta.php /* Title: Call to Action Description: Call to action element. Category: blockstudio Icon: lightbulb Mode: preview SupportsMode: false SupportsAlign: false */ $settings = [ 'text-align' => 'left' ]; ?> <p>Buy my product!</p>

Register variable

Alternatively, it is possible to bypass the file headers completely and register blocks via the $register variable:

<?php $register = [ 'title' => 'First Block', 'title' => __( 'First Block' ), 'category' => 'formatting', 'icon' => 'design', ]; ?> <p>My Markup</p>


Since version 1.3.0, BS supports Metabox blocks with the same known syntax. Since blocks are registed using the rwmb_meta_boxes filter, following snippet has to be added to the functions.php of your currently active theme:

add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) { $blockstudio = Blockstudio\Build::init( [ 'dir' => get_template_directory() . 'my-mb-blocks', 'prefix' => 'my-prefix', 'type' => 'mb' ] ); return array_merge( $meta_boxes, $blockstudio ); } );

The snippet above would register all blocks inside the my-mb-blocks folder of your current theme.


Blockstudio works with Advanced Custom Fields and Metabox, however, not all options are available for both plugins, the list above just shows all possible settings. Refer to the documentation of ACF or MB to find out which options are supported for each plugin.

Icons: SVGs will only work if no IconBackground or IconForeground is set. If one of those settings is present in the file headers, a Dashicons identifier has to be used.