Last modified:

Composing your own blocks with Blockstudio is extremely easy. The plugin will look for a blockstudio folder within your currently activated theme. Inside it, all subfolders which contain a block.json file with a blockstudio key will be registered.


      "apiVersion": 2,
      "name": "blockstudio/native",
      "title": "Native Block",
      "category": "text",
      "icon": "star-filled",
      "description": "Native Blockstudio block.",
      "keywords": [
      "version": "1.0.0",
      "textdomain": "blockstudio",
      "blockstudio": true



So far the custom block is not rendering any output. To fix that just create an index.php or index.twig in the same folder as your block.json file and its contents will automatically be rendered when your block is used.

                <!--index.php or index.twig-->
    <h1>My first native block.</h1>

Custom paths

By default, Blockstudio will recursively look through the blockstudio folder for blocks. You can change that behaviour in two ways.


                // Custom path within your theme.
    add_filter( 'blockstudio/path' , function () {
        return get_template_directory() . '/blocks';
    } );

    // Custom path within a plugin.
    add_filter( 'blockstudio/path' , function () {
        return plugins_url() . '/my-custom-plugin/blocks';
    } );



If the above options are not enough, it is possible to initiate the Blockstudio\Build class on various folders of your choice:

                add_action( 'acf/init', function () {
      // Blockstudio\Build::init( $args );
      Blockstudio\Build::init( [
        'dir'    => get_template_directory() . 'client-blocks',
        'type'   => 'native'
      ] );
    } );


Filter metadata

Metadata can be filtered before the block is being registered using the blockstudio/block/meta filter:

                add_filter('blockstudio/blocks/meta', function ($block) {
      if (strpos($block->name, 'blockstudio-element') === 0) {
        $block->blockstudio['icon'] ='<svg</svg>';

      return $block;
    } );


The example above is being used internally to give all Blockstudio library elements the same icon.