Components - InnerBlocks

Inner blocks allow you to insert additional blocks to your blocks. Under the hood, Blockstudio is using the InnerBlocks component. Please note that it is only possible to use one InnerBlocks component per block, this is a WordPress limitation.

Basic usage

To use InnerBlocks, you need to add the InnerBlocks component to your block.

index.php

<InnerBlocks /> or
<InnerBlocks/>Copy

The composition is up to you. You can nest the InnerBlocks component as deep as you want or just use it by itself.

Properties

allowedBlocks

The allowedBlocks prop allows you to define which blocks can be inserted into the InnerBlocks component.

index.php

index.twig

<InnerBlocks allowedBlocks="<?php echo esc_attr(wp_json_encode(['core/heading', 'core/paragraph'])); ?>" />Copy

<InnerBlocks allowedBlocks="{{ ['core/heading', 'core/paragraph']|json_encode|escape('html_attr') }}" />Copy

tag

By default, the InnerBlocks component is rendered as a div element. You can change this by using the tag prop.

index.php

<InnerBlocks tag="section" />Copy

template

The template prop allows you to define a template for the InnerBlocks component.

index.php

index.twig

<InnerBlocks template="<?php echo esc_attr( wp_json_encode([['core/heading', ['placeholder' => 'Book Title']], ['core/paragraph', ['placeholder' => 'Summary']]])); ?>" />Copy

<InnerBlocks template="{{ [['core/heading', { placeholder: 'Book Title' }], ['core/paragraph', { placeholder: 'Summary' }]]|json_encode|escape('html_attr') }}" />Copy

templateLock

The templateLock prop allows you to define if the template can be modified or not.

contentOnly: prevents all operations. Additionally, the block types that don't have content are hidden from the list view and can't gain focus within the block list. Unlike the other lock types, this is not overrideable by children.
all: prevents all operations. It is not possible to insert new blocks. Move existing blocks or delete them.
insert: prevents inserting or removing blocks, but allows moving existing ones.
false: prevents locking from being applied to an InnerBlocks area even if a parent block contains locking.

renderAppender

The renderAppender prop allows you to define the block appender type.

default: display the default block appender, typically the paragraph style appender when the paragraph block is allowed.
button: display a + icon button as the appender.

useBlockProps

useBlockProps will remove the outer wrapper of the InnerBlocks component inside the editor. See useBlockProps for more information.

Context

Registering

Blockstudio supports context for the InnerBlocks component. This allows you to pass data from the parent block to the child blocks. While it uses the WordPress core context mechanism under the hood, Blockstudio provides a more convenient API.

Instead of having to define all attributes that should be passed in the context separately, you can simply subscribe to all attributes of a parent block.

Let's say you have a container block setup like so:

block.json

{
  "$schema": "https://app.blockstudio.dev/schema",
  "name": "blockstudio/container",
  "title": "Container",
  "category": "design",
  "icon": "star-filled",
  "description": "Container block.",
  "blockstudio": {
    "attributes": [
      {
        "id": "full-width",
        "type": "toggle",
        "label": "Makes section full width"
      }
    ]
  }
}Copy

Inside your child block, simply use the usesContext property with the parent block name to gain access to all parent attributes in your block template.

block.json

{
  "$schema": "https://app.blockstudio.dev/schema",
  "name": "blockstudio/element",
  "title": "Element",
  "category": "design",
  "icon": "star-filled",
  "description": "Element block.",
  "usesContext": ["blockstudio/container"],
  "parent": ["blockstudio/container"],
  "blockstudio": true
}Copy

Templates

The $context and $c variables are available inside your block templates to access all parent attributes. Child blocks will automatically reload in the editor if parent data changes.

index.php

index.twig

<?php $container = $context['blockstudio/container']; ?>

<h1>
  <?php echo $container['full-width']
      ? 'is full width'
      : 'no full width'; ?>
</h1>Copy

{% set container = context['blockstudio/container'] %}

<h1>
  {{ container['full-width']
      ? 'is full width'
      : 'no full width' }}
</h1>Copy

Frontend wrapper

InnerBlocks has to render a wrapper element around its children inside the editor, however, it can be removed from the frontend by using blockstudio/blocks/components/innerblocks/frontend/wrap filter.

functions.php

add_filter('blockstudio/blocks/components/innerblocks/frontend/wrap', function ($render, $block) {
  if ($block->name === 'blockstudio/my-block') {
    $render = false;
  }

  return $render;
}, 10, 2);Copy

Return early

If you want to return early from the render method of your block, you can check if the $innerBlocks (it contains the <InnerBlocks/> content) variable is empty. This comes in handy if you don't want to render anything if there are no inner blocks.

index.php

<?php if (strip_tags($innerBlocks) === '') {
  return;
} ?>
<InnerBlocks tag="section" />Copy

Since <InnerBlocks/> is will always render an empty paragraph tag, you can use the strip_tags function to check if the content is empty.

Dynamic templates

The Select and Radio field types support dynamically generating the InnerBlocks template depending on the field value. This is useful if you want to allow the user to select a different template for the InnerBlocks component.

index.php

<InnerBlocks tag="section" />Copy

To do so, simply add a innerBlocks key to the options array with the template.

block.json

{
  "$schema": "https://app.blockstudio.dev/schema",
  "name": "blockstudio/type-select-innerblocks",
  "title": "Native Select InnerBlocks",
  "category": "blockstudio-test-native",
  "icon": "star-filled",
  "description": "Native Blockstudio Select InnerBlocks block.",
  "blockstudio": {
    "attributes": [
      {
        "id": "layout",
        "type": "select",
        "label": "Layout",
        "options": [
          {
            "value": "1",
            "label": "One",
            "innerBlocks": [
              {
                "name": "core/columns",
                "innerBlocks": [
                  {
                    "name": "core/column",
                    "innerBlocks": [
                      {
                        "name": "core/heading",
                        "attributes": {
                          "content": "This is the left Heading.",
                          "level": 1
                        }
                      },
                      {
                        "name": "core/paragraph",
                        "attributes": {
                          "content": "This is the left Paragraph."
                        }
                      }
                    ]
                  },
                  {
                    "name": "core/column",
                    "innerBlocks": [
                      {
                        "name": "core/heading",
                        "attributes": {
                          "content": "This is the right Heading.",
                          "level": 1
                        }
                      },
                      {
                        "name": "core/paragraph",
                        "attributes": {
                          "content": "This is the right Paragraph."
                        }
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "value": "2",
            "label": "Two",
            "innerBlocks": [
              {
                "name": "core/columns",
                "innerBlocks": [
                  {
                    "name": "core/column",
                    "innerBlocks": [
                      {
                        "name": "core/heading",
                        "attributes": {
                          "content": "This is the left Heading.",
                          "level": 2
                        }
                      },
                      {
                        "name": "core/paragraph",
                        "attributes": {
                          "content": "This is the left Paragraph."
                        }
                      }
                    ]
                  },
                  {
                    "name": "core/column",
                    "innerBlocks": [
                      {
                        "name": "core/heading",
                        "attributes": {
                          "content": "This is the right Heading.",
                          "level": 2
                        }
                      },
                      {
                        "name": "core/paragraph",
                        "attributes": {
                          "content": "This is the right Paragraph."
                        }
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ],
        "allowNull": "Select an option"
      }
    ]
  }
}Copy

× Close

Buy Now

× Close

/activating
Blockstudio can be activated on a site by navigating to the Blockstudio menu item in the WordPress admin dashboard. Alternatively, it is also possible to activate Blockstudio using PHP. This is done by adding the following code constant to your functions.php file: const BLOCKSTUDIO_LICENSE = "YOUR LICENSE KEY";
/assets
- code-field
  Beside static styles and scripts as files, Blockstudio also supports dynamic asset blocks via the [code field]({{ site.link }}/documentation/attributes/field-types#code). Depending on your use case, these can be scoped to the block.
- processing
- registering
  Blockstudio will automatically enqueue all files ending with .css, .scss and .js when your block is being used on a page. It is possible to define how assets are being enqueued by using one of the following file names. The * is a wildcard that can be replaced with any string of your choice. - *.(s)css: enqueues as a tag in the editor and on the frontend - *-inline.(s)css: enqueues the contents of the file in an inline
/attributes
- block-attributes
  The $attributes or $a variables only give you access to data registered in the blockstudio property. To access information about standard block data like alignment or typography, simply use the $block or $b variables.
- conditional-logic
  Fields can be shown depending on conditions.
- disabling
  Attributes can be deactivated on a per-block basis by hovering over the left side of the UI in the sidebar and clicking it when the blue border appears. This comes in handy when an attribute should be disabled temporarily, while leaving the filled content intact. The UI of the attribute will be slightly translucent if it is deactivated. The same principle also works for single elements when using the files attribute type:
- field-types
- filtering
  Blockstudio provides two methods to filter block attributes.
- html-utilities
  Sometimes it might be necessary to use the value of attributes inside your CSS or JS files. Blockstudio provides two helper functions to render the value of attributes as data attributes or CSS variables. Let's imagine a block with the following attribute structure: "blockstudio": { "attributes": [ { "id": "message", "type": "text", "label": "My message" }, { "id": "color", "type": "color", "label": "My color" } ] }
- populating-options
  Instead of supplying different field types like Posts, Users or Terms, Blockstudio allows for a more modular way of populating data right from the block.json. This feature currently works for select, radio,checkbox, color and gradient field types. Data can be populated in three different ways: - Query return results from a post, user or term query (only select, radio, checkbox) - Fetch return results from an external source (only select, radio,checkbox) - Function return results from a custom function - Custom return results from a custom dataset
- registering
  Of course, blocks without dynamic data are kinda boring! Attributes allow you to add data to your blocks and are comparable to custom fields that you know from solutions like ACF or Metabox. Custom attributes are registered using the blockstudio property inside the block.json file. { "$schema": "https://app.blockstudio.dev/schema", "name": "blockstudio/native", "title": "Native Block", "category": "text", "icon": "star-filled", "description": "Native Blockstudio block.", "supports": { "align": true }, "blockstudio": { "attributes": [ { "id": "message", "type": "text", "label": "My message" } ] } } And that's it! You've just registered your first custom attribute:
- rendering
  Inside template files, all attributes can be accessed using the $attributes or $a variables and the respective ID of the field.
  
  {{ attributes.message }}
  
  {{ a.message }}
  Attribute values render false if the field is empty or no option has been selected.
  
  {{ a.message }}
/code-snippets
Although Blockstudios main focus is on custom blocks, its file-first approach is also suitable for code snippets.
- #setup
  To create a new code snippet, simply create a new folder and place an init.php file in it. Blockstudio will always execute that file. For more information on the init file, check the [Initialization]({{ site.link }}/documentation/initialization/) page.
- #styles-and-scripts
  Folders marked as code snippets will also process and enqueue styles and scripts. To enqueue global styles and scripts, use the global [prefix for the asset name]({{ site.link }}/documentation/assets/registering/#global). Assets inside code snippet folders also support all [processing]({{ site.link }}/documentation/assets/processing/).
- #custom-directories
  The above technique can also be used on directories outside of the folder where all blocks are stored. For example, let's say you want to store global assets like styles and scripts inside your theme. Simply create a new Blockstudio instance using the [init method]({{ site.link }}/documentation/registration/#instances). add_action('init', function () { Blockstudio\\Build::init([ 'dir' => get_template_directory() . '/assets' ]); }); Now, simply follow the setup instructions inside the to register a code snippet inside the assets folder.
/components
- innerblocks
  Inner blocks allow you to insert additional blocks to your blocks. Under the hood, Blockstudio is using the InnerBlocks component. Please note that it is only possible to use one InnerBlocks component per block, this is a WordPress limitation.
- mediaplaceholder
  The MediaPlaceholder component provides a placeholder to add media items to a block. The same component is being used in the core/image block. It is based on the React component with the same name.
- richtext
  The RichText component allows rendering an editable input inside the editor and a static HTML Element in the frontend. It is based on the RichText component WordPress provides.
- useblockprops
  By default, Gutenberg has to create a wrapper around blocks to make them interactive inside the editor. This can become problematic for some block types like containers or columns, since the markup between editor and frontend will be different. The useBlockProps hook makes it possible to mark an element inside the block template as the root element, thus creating markup parity between editor and frontend.
/composer
Blockstudio can be added to projects using composer with the private-composer-installer package. It allows you to install packages from private URLs within composer.json.
- #env
  It is good practice to store all your credentials and private keys in an .env file. If you haven't done so already, create a .env file in the root of your project and add your Blockstudio license key BLOCKSTUDIO_KEY=your-blockstudio-license-key
- #composer-json
  Below is an example composer.json file that uses the private-composer-installer. { "name": "my-company/my-project", "description": "WordPress plugin.", "license": "proprietary", "repositories": [ { "type": "package", "package": { "name": "fabrikat/blockstudio", "version": "4.0.2", "type": "vendor", "dist": { "type": "zip", "url": "https://blockstudio.dev/download?v={%VERSION}&k={%BLOCKSTUDIO_KEY}" }, "require": { "ffraenz/private-composer-installer": "^5.0.1" } } } ], "config": { "allow-plugins": { "composer/installers": true, "ffraenz/private-composer-installer": true } }, "require": { "fabrikat/blockstudio": "^4.0.2", } }
/context
When blocks are used inside a loop (for example, a Query block), the block is executed once for each iteration of the loop. Blockstudio provides handy shortcuts for accessing the current loop and outer context.

This is the data of current element inside the loop:

This is the data the current post:

This is the data of current element inside the loop: {{ block.context.postId }} {{ block.context.postType }}

This is the data the current post: {{ block.postId }} {{ block.postType }}
/editor
- examples
  The default value for attributes will be used in the editor. If you prefer to preview the block with different data, you can use the example key. Keep in mind that the example data will be also be used when [previewing]({{ site.link }}/documentation/environment/#preview) the block
- general
  Blockstudio includes a full code editor, capable of editing and creating blocks all within the WordPress admin area. The current feature set includes: - Creating a custom plugin if no block source has been found - Creating new files - Editing files - Renaming files - Deleting files - Creating new blocks - Deleting blocks - Importing data - Exporting data - Editing assets - Adding assets - Deleting assets - Live preview of blocks
- gutenberg
  Since 5.2, it is possible to edit blocks directly from Gutenberg. By clicking the "Edit with Blockstudio" button in the sidebar, the editor will open in a separate window and allow you to make changes to the block itself or its assets and preview them inside Gutenberg. Editing blocks using this method has one advantage over the built-in editor preview that Blockstudio provides: the same block inserted multiple times with different settings can be previewed at once. Please note that the editor needs to be active in order for the preview button to show up.
- tailwind
  Blockstudio supports writing Tailwind directly in the editor.
/environment
Sometimes it is necessary to show content in your blocks exclusively when it is being rendered inside the Gutenberg editor and not on the frontend. This technique is very useful to provide users with helpful information and placeholders if the necessary data hasn't been input yet.
- #editor
  This content is only going to be rendered inside the editor. This content is only going to be rendered on the frontend. This content is only going to be rendered inside the editor. This content is only going to be rendered on the frontend.
- #preview
  Blockstudio adds another environment variable that will come in handy for block developers. $isPreview allows you to conditionally render content inside the block preview window when hovering over a block inside the block inserter. This content is only going to be rendered inside the block preview. This content is only going to be rendered on the frontend and editor. This content is only going to be rendered inside the block preview. This content is only going to be rendered on the frontend and editor.
/extensions
Extensions allow you to extend any registered block in your WordPress installation using a simple .json based API, which is similar to the block.json configuration. This includes core, third-party and blocks made with Blockstudio. All [field types]({{ site.url }}/documentation/attributes/field-types) can be added to any block, with the data being saved to the block's attributes. The complete feature set of attributes like [filtering]({{ site.url }}/documentation/attributes/filtering), [disabling]({{ site.url }}/documentation/attributes/disabling), [conditional logic]({{ site.url }}/documentation/attributes/conditional-logic) and [populating options]({{ site.url }}/documentation/attributes/populating-options) are available for extensions.
- #extension-types
  Extended values can now be utilized in more versatile ways: - class: Add a class using the attribute value to the block. - style: Add inline styles using the attribute value to the block. - attributes: Set any attribute value directly on the block, enhancing its functionality or accessibility. - data attributes: Use extension values to set specific data attributes, enabling more complex interactions and dynamic content adjustments.
- #setup
  Imagine the following scenario: you want to add a custom class select field to every core block. All you need to do is add this .json file anywhere in your block folder, and it will be automatically registered as an extension. { "$schema": "https://app.blockstudio.dev/schema/extend", "name": "core/*", "priority": 10, "blockstudio": { "extend": true, "attributes": [ { "id": "customColor", "type": "select", "label": "Custom color", "options": [ { "value": "#f00", "label": "Red" }, { "value": "#00f", "label": "Blue" } ], "set": [ { "attribute": "style", "value": "color: {attributes.customColor}" } ] } ] } } This will add a customColor field to every core block, allowing you to set the color of the block's text. Let's break down the configuration from top to bottom:
- #file-name
  Since there is no rendering template, an extension doesn't need a matching index file and thus doesn't need to be named block.json. This allows storing all extensions conveniently in a single folder.
- #schema
  Blockstudio provides a custom JSON schema for extension configurations: View Extension schema
- #name
  The name property of the configuration object defines which blocks should be extended. There are three options depending on your needs: - blockName: A single block name, e.g. core/paragraph. - [blockNameA, blockNameB]: An array of block names, e.g. ["core/paragraph", "core/heading"]. - core/*: A wildcard to extend all blocks of a certain type, e.g. core/*.
- #blockstudio-key
  Just like when using block.json for custom blocks, the blockstudio property has to be present in the configuration object with extend set to true.
- #position
  By default, extensions will render in its own tab in the block inspector. If you want to move the extensions to a different position, you can use the group property. The following values are currently available: - settings: The default position. - styles: The styles tab. - advanced: The advanced tab. { "$schema": "https://app.blockstudio.dev/schema/extend", "name": "core/*", "blockstudio": { "extend": true, "group": "styles", "attributes": [] } }
- #priority
  The priority property allows you to define the order in which extensions are rendered. Extensions with a higher priority will be rendered later. This is useful if you want an extension to appear before another one.
- #attributes
  For more information on how attributes work, please refer to the [attributes section]({{ site.url }}/documentation/attributes/field-types). The only thing you need to know about attributes inside extensions is the set property. It is used to apply the value of the attribute to one of the [types]({{ site.url }}/documentation/extensions#extension-types) of the block. For example, the following configuration will set the style attribute of the block to color: red or color: blue depending on the value of the select field. { "$schema": "https://app.blockstudio.dev/schema/extend", "name": "core/*", "blockstudio": { "extend": true, "attributes": [ { "id": "customColor", "type": "select", "label": "Heading color", "options": [ { "value": "#f00", "label": "Red" }, { "value": "#00f", "label": "Blue" } ], "set": [ { "attribute": "style", "value": "color: {attributes.customColor}" } ] } ] } }
- #getting-values
  Dot notation inside curly braces is used to get the value of an attribute. It is also possible to get nested values when attributes are not returning a single value, for example, when setting the return format to both on field types with options. { "attributes": [ { "id": "customColor", "type": "select", "label": "Heading color", "options": [ { "value": "#f00", "label": "Red" }, { "value": "#00f", "label": "Blue" } ], "returnFormat": "both", "set": [ { "attribute": "style", "value": "color: {attributes.customColor.value}" }, { "attribute": "data-color", "value": "{attributes.customColor.label}" } ] } ] } The example above will set the style attribute to color: #f00 or color:#00f and the data-color attribute to Red or Blue depending on the value. For now, only values from the current attribute can be used inside set definitions. The ability to use values from other attributes might be added in the future.
- #arrays
  When using arrays, the set property will be applied to every item in the array.
- #attributes-field
  When using the attributes field, there is no set property needed, as the field automatically maps the values to the attribute name and value
/general
- #introduction
  Blockstudio enables you to create custom WordPress blocks with nothing but PHP using the WordPress block.json format. It greatly simplifies the developer experience in regard to block registration, lazy loading assets, and custom fields.
- #core-focused
  There is no secret sauce. Blockstudio is built on top of core WordPress features and Gutenberg components. It is designed to be a lightweight abstraction layer that helps you get started with custom blocks quickly.
- #server-side-first
  When creating dynamic blocks using nothing but WordPress, there is duplication of logic between PHP and JS code. There are discussions about solving this issue, including hydrating blocks on the client side (not good for SEO) or introducing a JSX parser for PHP (complex). Blockstudio takes a different approach. You use PHP to write your block templates and sprinkle in interactivity like or using JSX-like tags. Inside the editor, those tags will be replaced with their React counterparts. On the frontend, the tags will be replaced with HTML content. This way, you get the best of both worlds: a server-side rendered block with great interactivity in the editor.
- #file-system-based
  While WordPress supports a file-based approach using the WPDefinedPath string type, it is also possible to link assets or templates from other destinations. Blockstudio doubles down on the file-system as the primary (and only) way of registering blocks. This decision was not made to restrict, but to set a block structure in place that can't be argued with. For example, if a style.css or script.js file is found in the same folder as a block.json, then you can be sure that it belongs to this exact block only.
- #no-setup
  Blockstudio just works. It is designed to remove friction when composing custom blocks and doesn't come in your way while doing so. Want to use Twig for your template? Simply rename the file extension. Need to include some CSS? Create a style.css file. Blockstudio will automatically enqueue it whenever the block is being used on your page, even when it is used outside the post_content with the [rendering function]({{ site.url }}/documentation/rendering-blocks). Do you have feature requests or questions? Message us.
/hooks
- javascript
  Besides PHP hooks, Blockstudio also provides JavaScript events to manipulate values and blocks inside the editor. Since events are tied to block names and attribute IDs, we will use namespace/my-block as the name in the following examples. Of course, you will need to replace it with your own block name.
- php
  Below you'll find a list of all available PHP hooks that can be used to extend or adjust the functionality of the plugin.
/initialization
Block templates will only be executed when the block is rendered. This is enough for most blocks; however, sometimes you need to execute code during an earlier stage of execution. For example, you may want to register a new post type or do some other type of setup unrelated to the block. To do this, you can add a PHP file that starts with init-, like init.php or init-post-types.php to your block directory. This file is executed during the init action. For more information on this specific stage, see the WordPress documentation. Any init.php file that is found within the block directory will be executed, regardless if it is part of a block context or not. This makes it perfect for organizing code snippets that are not related to any certain blocks.
/library
Since version 3.1.0, Blockstudio includes a library of prebuilt elements. Of course, these elements are making use of all the features that are available to Blockstudio users. In fact, the library is actively being used to dogfood our own product, helping us fast-track development and ensure a good developer experience for everyone. The library is a first step in making Blockstudio more available as a general collection of ready-to-use blocks for non developers, all the while being built with the most advanced block framework for WordPress. More blocks are actively being developed!
- #activating
- #blocks
/loading
Blockstudio blocks are dynamic, meaning that they must be rendered on the server to be displayed in Gutenberg. This rendering is facilitated by a fetch call to the Blockstudio block renderer. Upon first opening the editor, each block fetches its respective template, which results in multiple requests depending on the number of blocks present on the page. On some hosts, this can cause timeouts and errors while loading other essential assets needed for the editor to function properly.
- #disabling
  Rendering template loading can be disabled by setting the disableLoading key in block.json to true. A placeholder will be rendered in place of the block template. All field settings will still be available when opening the sidebar. { "name": "blockstudio/native", "title": "Native Block", "category": "text", "icon": "star-filled", "description": "Native Blockstudio block.", "blockstudio": { "blockEditor": { "disableLoading": true } } } }
/overrides
Blockstudio includes the possibility to override blocks on a very granular level. This can be useful for shared block libraries when you want to change the behavior of a block without having to create a new block from scratch.
- #block-json
  To get started, set the name of the block you want to override as the name key and set the override key to true. { "name": "blockstudio/my-block", "title": "My overridden block title", "blockstudio": { "override": true } } When the override property is set to true, the data from the new block.json will be merged with the data from the original block. This means that you can override any property of the original block.
- #attributes
  Attributes can either be overridden by id or added additionally. For example, let's imagine that we want to override the width attribute of a block and add a new height attribute. { "name": "blockstudio/my-block", "title": "My overridden block title", "blockstudio": { "override": true, "attributes": [ { "id": "width", "type": "number", "default": 280, "label": "Override width" }, { "id": "height", "type": "number", "default": 280, "label": "New height" } ] } } When an attribute with the same id is found, the data will be merged with the original attribute. Attributes which are not found will be added to the block. Important: When overriding attributes, you have to provide the type of the original attribute, even if it stays the same.
- #complex-structures
  When overriding attributes with complex structures (repeaters, groups, tabs, etc.), you have to provide the full structure of the attribute to the point of the item that should be overridden. { "name": "blockstudio/my-block", "blockstudio": { "override": true, "attributes": [ { "id": "tabs", "type": "tabs", "tabs": [ { "id": "tab1", "attributes": [ { "key": "group1", "type": "group", "title": "Group", "attributes": [ { "id": "text", "type": "text", "label": "Override text" } ] } ] }, { "id": "tab2", "title": "Override tab", "attributes": [ { "id": "group", "type": "group", "title": "Group ID", "attributes": [ { "id": "text", "type": "text", "label": "Override text" } ] } ] } ] } ] } }
- #assets
  Asset files will be replaced when the file name matches. For example, if a style.css file exists in the original block, it will be replaced by the style.css file in the overriding block. Files with names that do not match the original block will be added to the block.
- #rendering-template
  Rendering templates can be overridden by providing a new template file, so either index.php or index.twig.
- #twig-blocks
  Twig templates can be overridden on a more granular level using the block feature in Twig. Let's imagine the following rendering template for a fictional image block:
  Images:
  
  Instead of replacing the whole template, we can use Twigs extends feature to override certain parts of the template while keeping the rest intact. {% block image %} <figure> <img src="{{ image.url }}" class="image" /> <figcaption>{{ image.caption }}</figcaption> </figure> {% endblock %}
/post-meta
Since block templates are just normal PHP files, you can use any PHP code you want in them. However, since blocks don't have access to the global $post variable inside the editor, get_the_ID() and other functions that depend on the variable will only work on the frontend. Blockstudio provides four different ways to access the current post ID in the editor and the frontend. echo $post_id; echo $postId; echo $block['postId']; echo $b['postId']; {{ post_id }}; {{ postId }}; {{ block.postId }}; {{ b.postId }};
- #getting-post-meta
  All common custom field plugins and WordPress itself provide the possibility to access post meta using a post ID.
- #acf
  echo get_field('field_name', $post_id); {{ fn('get_field', 'field_name', postId) }};
- #metabox
  echo rwmb_get_value('field_id', null, $post_id); {{ fn('rwmb_get_value', 'field_id', postId) }};
- #refreshing-blocks
  By default, blocks won't be refreshed when you save or update a post. Thus, old data might be displayed in the editor after saving. To fix this, you can use the refreshOn key inside your block.json to tell Blockstudio to refresh the block when a post is saved. { "name": "blockstudio/native", "title": "Native Block", "category": "text", "icon": "star-filled", "description": "Native Blockstudio block.", "blockstudio": { "refreshOn": [ "save" ] } }
/preview
Gutenberg allows previewing blocks when hovering over the block in the fixed block inserter. To enable the preview of blocks made with Blockstudio, simply set the example key to an empty object. { "name": "blockstudio/native", "title": "Native Block", "category": "text", "icon": "star-filled", "description": "Native Blockstudio block.", "example": {}, "blockstudio": true }
- #custom-data
  It is also possible to provide structured data in the example key, so any custom attributes are correctly being rendered. { "name": "blockstudio/native", "title": "Native Block", "category": "text", "icon": "star-filled", "description": "Native Blockstudio block.", "example": { "attributes": { "title": "This title will be shown in the preview" } }, "blockstudio": true }
  
  {{ a.title }}
- #innerblocks
  If your block relies on InnerBlocks, it is possible to provide a template for the InnerBlocks. { "name": "blockstudio/native", "title": "Native Block", "category": "text", "icon": "star-filled", "description": "Native Blockstudio block.", "example": { "innerBlocks": [ { "name": "core/paragraph", "attributes": { "content": "This is the default InnerBlocks block." } } ] }, "blockstudio": true }
/registration
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 that contain a block.json file with a blockstudio key will be registered.
- #block-json
  { "name": "blockstudio/native", "title": "Native Block", "category": "text", "icon": "star-filled", "description": "Native Blockstudio block.", "blockstudio": true }
- #template
  So far, the custom block is not going to be registered since it is missing a template. 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.
  My first native block.
- #twig
  Twig is a flexible, fast, and secure template engine for PHP. It allows developers to write concise and readable code in templates, enhancing productivity and maintainability. Twig supports a variety of features designed to make templating both powerful and straightforward, making it ideal for projects that require robust, reusable templates.
- #conditional-logic
  Blocks can be registered conditionally using the conditions key. It supports all the global variables which are also available for attributes. See all conditions The following example will only register the block if the current post type is a page: { "blockstudio": { "conditions": [ [ { "type": "postType", "operator": "==", "value": "page" } ] ], } }
- #custom-icon
  Custom SVGs icons for blocks can be registered like so: { "blockstudio": { "icon": "" } } WordPress doesn't allow for custom SVG icons inside its own block.json icon key, only Dashicons IDs are allowed here.
- #html
  Blockstudio is using a React element parser to render the icon element, so it is possible to use HTML inside the icon string. { "blockstudio": { "icon": "
  :-)
  " } }
- #custom-paths
  By default, Blockstudio will recursively look through the blockstudio folder inside your current theme or child theme for blocks. You can change that behaviour in two ways.
- #filter
  // 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'; });
- #instances
  If the above options are not enough, it is possible to initiate the Blockstudio\\Build class on various folders of your choice: add_action('init', function () { Blockstudio\\Build::init([ 'dir' => get_template_directory() . '/client-blocks' ]); });
- #filter-metadata
  Metadata can be filtered before the block is being registered using the blockstudio/block/meta filter: The example above is being used internally to give all Blockstudio library elements the same icon.
/rendering
With Gutenberg becoming the prominent instrument in creating easily editable websites for clients, it makes sense to create all necessary website areas as blocks. While this approach will cater to most, advanced users and specific use cases might need to use those existing blocks outside the editor. Blockstudio provides two specific functions for exactly this use case: - bs_render_block: immediately renders the block to the page (no "echo "needed) - bs_block: needs an "echo" to be rendered to the page. This function is useful when nesting blocks. All Blockstudio specific features like inline styles, scripts, and scoped styles are supported when using the render functions.
- #without-data
  In its simplest form, the function accepts a single value which is the ID of the block that should be rendered on the page. bs_render_block('blockstudio/cta');
- #with-data
  To render the block with custom data, an array needs to be used in place of a single value for the first parameter. The value in the data key will be passed to the $attributes and $a variable inside your block template. bs_render_block([ 'id' => 'blockstudio/cta', 'data' => [ 'title' => 'My title', 'subtitle' => 'My subtitle', ], ]);
- #nesting
  Blocks can be nested within each other using the bs_block function in combination with the powerful $content variable inside your block templates.
  
  echo bs_block([ 'id' => 'blockstudio/cta', 'data' => [ 'title' => 'My title', 'subtitle' => 'My subtitle', ], 'content' => bs_block([ 'id' => 'blockstudio/cta', 'data' => [ 'text' => 'Button Text', ], ]) ]); The button block will be rendered in place of the $content variable inside the block template.
- #multiple-slots
  It is also possible to create multiple content slots by simply making the $content variable an associative array and calling it approriate keys in the bs_block function.
  
  echo bs_block([ 'id' => 'blockstudio/cta', 'data' => [ 'title' => 'My title', 'subtitle' => 'My subtitle', ], 'content' => [ 'beforeContent' => bs_block([ 'id' => 'blockstudio/badge', 'data' => ['text' => 'Before Content'], ]), 'afterContent' => bs_block([ 'id' => 'blockstudio/cta', 'data' => ['text' => 'Button Text'], ]) ] ]);
/schema
To improve development with autocomplete and validation in your IDE, Blockstudio introduces its own schema: View Blockstudio schema The Blockstudio schema is an (always up-to-date) copy of the WordPress core block.json schema with an additional blockstudio property that houses all plugin features like field schemas without interfering with potential future core properties
- #add-to-json
  Simply add a $schema key with a value of https://app.blockstudio.dev/schema to your block.json and your IDE should start to give you hints about Blockstudio specific properties. { "$schema": "https://app.blockstudio.dev/schema", "name": "blockstudio/native", "title": "Native Block", "category": "text", "icon": "star-filled", "description": "Native Blockstudio block.", "blockstudio": true }
/settings
Blockstudio includes a powerful settings API, that allows setting options via a blockstudio.json file inside your theme folder and/or filters. Additionally, allowed users are able to change the settings visually inside the admin area.
- #json
  If a blockstudio.json file is present inside your theme folder, it will be used to set the default options for the current site. A JSON schema is available to validate the file and help with autocompletion when used in an IDE. The following properties are available. { "$schema": "https://app.blockstudio.dev/schema/blockstudio", "users": { "ids": [], "roles": [] }, "assets": { "enqueue": true, "minify": { "css": false, "js": false }, "process": { "scss": false } }, "editor": { "formatOnSave": false, "assets": [], "markup": false }, "library": false }
- #filters
  Alternatively you can use the blockstudio/settings/${setting} filter to set options via PHP for more flexibility. add_filter('blockstudio/settings/assets/enqueue', '__return_false'); add_filter('blockstudio/settings/editor/formatOnSave', '__return_true'); add_filter('blockstudio/settings/library', '__return_true'); Options set via the blockstudio/settings/${setting} filter will override the ones set via the blockstudio.json file. Both methods can be used together.
- #admin
  Allowed users from the blockstudio/settings/users/ids and blockstudio/settings/users/roles filters are able to change the settings visually inside the admin area. If the Save as JSON checkbox is checked, the settings will be saved to the JSON file, otherwise they will be saved to the database into the options table. Settings set via filters will be grayed out and disabled inside the admin area.
/transforms
The Block Transforms API allows you to define ways in how to transform blocks. Blockstudio currently supports three different types: - block to block: transform a block into another block - enter: insert a block when the user enters text and presses Enter - prefix: insert a block when the user enters text and presses Space
- #block-to-block
  Block to block transforms allow you to transform a block into another block. { "$schema": "https://app.blockstudio.dev/schema", "name": "blockstudio/transforms", "title": "Native Transforms", "icon": "star-filled", "description": "Native Blockstudio Transforms.", "blockstudio": { "transforms": { "from": [ { "type": "block", "blocks": [ "blockstudio/transforms-2", "blockstudio/transforms-3" ] } ] }, "attributes": [ { "id": "text", "type": "text", "label": "Text" } ] } } When transforming into the new block, the attributes of the old block will be passed to the new block. In the example above, the text attribute will be passed to the new block. The same goes for all InnerBlocks content. It is important to note that the attribute types have to be the same for the block being transformed into and the block being transformed from. For example, if the block being transformed into has an attribute with the ID of text but the type of number, it won't appear in the transform list, as this would cause a type mismatch and rendering error. The number of attributes between the two blocks doesn't have to be the same.
- #enter
  Enter transforms allow you to insert a block when the user types certain content and then presses the Enter key. { "blockstudio": { "transforms": { "from": [ { "type": "enter", "regExp": "/^-{3,}$/" } ] } } } In the example above, the block will be inserted when the user types three or more dashes (-) and then presses Enter.
- #prefix
  Prefix transforms allow you to insert a block when the user types certain content and then presses the Space key. { "blockstudio": { "transforms": { "from": [ { "type": "prefix", "regExp": "???" } ] } } } In the example above, the block will be inserted when the user types three question marks (?) and then presses Space.
/variations
The Block Variation API allows you to register custom variations for existing blocks. Let's imagine a block that should have two different variations depending on the value of a simple select field. { "$schema": "https://app.blockstudio.dev/schema", "name": "blockstudio/variations", "title": "Native Variation", "description": "Native Blockstudio Variation block.", "icon": "star-filled", "variations": [ { "name": "variation-2", "title": "Native Variation 2", "description": "Native Blockstudio Variation block 2.", "attributes": { "select": { "value": "variation-2" } } } ], "blockstudio": { "attributes": [ { "id": "select", "type": "select", "label": "Select", "options": [ { "value": "variation-1", "label": "Variation 1" }, { "value": "variation-2", "label": "Variation 2" } ], "default": { "value": "variation-1" } } ] } } The above will create three blocks in the inserter, the main one, and two variations.
- #hiding-attributes
  Attributes will automatically render the appropriate input in the sidebar. Since variation blocks depend on specific attribute values, you might want to hide those fields from the sidebar. To do so, you can use the hidden option. { "blockstudio": { "attributes": [ { "id": "select", "type": "select", "label": "Select", "hidden": true, "options": [ { "value": "variation-1", "label": "Variation 1" }, { "value": "variation-2", "label": "Variation 2" } ] } ] } }

× Close

Navigation

× Close

/activating
Blockstudio can be activated on a site by navigating to the Blockstudio menu item in the WordPress admin dashboard. Alternatively, it is also possible to activate Blockstudio using PHP. This is done by adding the following code constant to your functions.php file: const BLOCKSTUDIO_LICENSE = "YOUR LICENSE KEY";
/assets
- code-field
  Beside static styles and scripts as files, Blockstudio also supports dynamic asset blocks via the [code field]({{ site.link }}/documentation/attributes/field-types#code). Depending on your use case, these can be scoped to the block.
- processing
- registering
  Blockstudio will automatically enqueue all files ending with .css, .scss and .js when your block is being used on a page. It is possible to define how assets are being enqueued by using one of the following file names. The * is a wildcard that can be replaced with any string of your choice. - *.(s)css: enqueues as a tag in the editor and on the frontend - *-inline.(s)css: enqueues the contents of the file in an inline
/attributes
- block-attributes
  The $attributes or $a variables only give you access to data registered in the blockstudio property. To access information about standard block data like alignment or typography, simply use the $block or $b variables.
- conditional-logic
  Fields can be shown depending on conditions.
- disabling
  Attributes can be deactivated on a per-block basis by hovering over the left side of the UI in the sidebar and clicking it when the blue border appears. This comes in handy when an attribute should be disabled temporarily, while leaving the filled content intact. The UI of the attribute will be slightly translucent if it is deactivated. The same principle also works for single elements when using the files attribute type:
- field-types
- filtering
  Blockstudio provides two methods to filter block attributes.
- html-utilities
  Sometimes it might be necessary to use the value of attributes inside your CSS or JS files. Blockstudio provides two helper functions to render the value of attributes as data attributes or CSS variables. Let's imagine a block with the following attribute structure: "blockstudio": { "attributes": [ { "id": "message", "type": "text", "label": "My message" }, { "id": "color", "type": "color", "label": "My color" } ] }
- populating-options
  Instead of supplying different field types like Posts, Users or Terms, Blockstudio allows for a more modular way of populating data right from the block.json. This feature currently works for select, radio,checkbox, color and gradient field types. Data can be populated in three different ways: - Query return results from a post, user or term query (only select, radio, checkbox) - Fetch return results from an external source (only select, radio,checkbox) - Function return results from a custom function - Custom return results from a custom dataset
- registering
  Of course, blocks without dynamic data are kinda boring! Attributes allow you to add data to your blocks and are comparable to custom fields that you know from solutions like ACF or Metabox. Custom attributes are registered using the blockstudio property inside the block.json file. { "$schema": "https://app.blockstudio.dev/schema", "name": "blockstudio/native", "title": "Native Block", "category": "text", "icon": "star-filled", "description": "Native Blockstudio block.", "supports": { "align": true }, "blockstudio": { "attributes": [ { "id": "message", "type": "text", "label": "My message" } ] } } And that's it! You've just registered your first custom attribute:
- rendering
  Inside template files, all attributes can be accessed using the $attributes or $a variables and the respective ID of the field.
  
  {{ attributes.message }}
  
  {{ a.message }}
  Attribute values render false if the field is empty or no option has been selected.
  
  {{ a.message }}
/code-snippets
Although Blockstudios main focus is on custom blocks, its file-first approach is also suitable for code snippets.
- #setup
  To create a new code snippet, simply create a new folder and place an init.php file in it. Blockstudio will always execute that file. For more information on the init file, check the [Initialization]({{ site.link }}/documentation/initialization/) page.
- #styles-and-scripts
  Folders marked as code snippets will also process and enqueue styles and scripts. To enqueue global styles and scripts, use the global [prefix for the asset name]({{ site.link }}/documentation/assets/registering/#global). Assets inside code snippet folders also support all [processing]({{ site.link }}/documentation/assets/processing/).
- #custom-directories
  The above technique can also be used on directories outside of the folder where all blocks are stored. For example, let's say you want to store global assets like styles and scripts inside your theme. Simply create a new Blockstudio instance using the [init method]({{ site.link }}/documentation/registration/#instances). add_action('init', function () { Blockstudio\\Build::init([ 'dir' => get_template_directory() . '/assets' ]); }); Now, simply follow the setup instructions inside the to register a code snippet inside the assets folder.
/components
- innerblocks
  Inner blocks allow you to insert additional blocks to your blocks. Under the hood, Blockstudio is using the InnerBlocks component. Please note that it is only possible to use one InnerBlocks component per block, this is a WordPress limitation.
- mediaplaceholder
  The MediaPlaceholder component provides a placeholder to add media items to a block. The same component is being used in the core/image block. It is based on the React component with the same name.
- richtext
  The RichText component allows rendering an editable input inside the editor and a static HTML Element in the frontend. It is based on the RichText component WordPress provides.
- useblockprops
  By default, Gutenberg has to create a wrapper around blocks to make them interactive inside the editor. This can become problematic for some block types like containers or columns, since the markup between editor and frontend will be different. The useBlockProps hook makes it possible to mark an element inside the block template as the root element, thus creating markup parity between editor and frontend.
/composer
Blockstudio can be added to projects using composer with the private-composer-installer package. It allows you to install packages from private URLs within composer.json.
- #env
  It is good practice to store all your credentials and private keys in an .env file. If you haven't done so already, create a .env file in the root of your project and add your Blockstudio license key BLOCKSTUDIO_KEY=your-blockstudio-license-key
- #composer-json
  Below is an example composer.json file that uses the private-composer-installer. { "name": "my-company/my-project", "description": "WordPress plugin.", "license": "proprietary", "repositories": [ { "type": "package", "package": { "name": "fabrikat/blockstudio", "version": "4.0.2", "type": "vendor", "dist": { "type": "zip", "url": "https://blockstudio.dev/download?v={%VERSION}&k={%BLOCKSTUDIO_KEY}" }, "require": { "ffraenz/private-composer-installer": "^5.0.1" } } } ], "config": { "allow-plugins": { "composer/installers": true, "ffraenz/private-composer-installer": true } }, "require": { "fabrikat/blockstudio": "^4.0.2", } }
/context
When blocks are used inside a loop (for example, a Query block), the block is executed once for each iteration of the loop. Blockstudio provides handy shortcuts for accessing the current loop and outer context.

This is the data of current element inside the loop:

This is the data the current post:

This is the data of current element inside the loop: {{ block.context.postId }} {{ block.context.postType }}

This is the data the current post: {{ block.postId }} {{ block.postType }}
/editor
- examples
  The default value for attributes will be used in the editor. If you prefer to preview the block with different data, you can use the example key. Keep in mind that the example data will be also be used when [previewing]({{ site.link }}/documentation/environment/#preview) the block
- general
  Blockstudio includes a full code editor, capable of editing and creating blocks all within the WordPress admin area. The current feature set includes: - Creating a custom plugin if no block source has been found - Creating new files - Editing files - Renaming files - Deleting files - Creating new blocks - Deleting blocks - Importing data - Exporting data - Editing assets - Adding assets - Deleting assets - Live preview of blocks
- gutenberg
  Since 5.2, it is possible to edit blocks directly from Gutenberg. By clicking the "Edit with Blockstudio" button in the sidebar, the editor will open in a separate window and allow you to make changes to the block itself or its assets and preview them inside Gutenberg. Editing blocks using this method has one advantage over the built-in editor preview that Blockstudio provides: the same block inserted multiple times with different settings can be previewed at once. Please note that the editor needs to be active in order for the preview button to show up.
- tailwind
  Blockstudio supports writing Tailwind directly in the editor.
/environment
Sometimes it is necessary to show content in your blocks exclusively when it is being rendered inside the Gutenberg editor and not on the frontend. This technique is very useful to provide users with helpful information and placeholders if the necessary data hasn't been input yet.
- #editor
  This content is only going to be rendered inside the editor. This content is only going to be rendered on the frontend. This content is only going to be rendered inside the editor. This content is only going to be rendered on the frontend.
- #preview
  Blockstudio adds another environment variable that will come in handy for block developers. $isPreview allows you to conditionally render content inside the block preview window when hovering over a block inside the block inserter. This content is only going to be rendered inside the block preview. This content is only going to be rendered on the frontend and editor. This content is only going to be rendered inside the block preview. This content is only going to be rendered on the frontend and editor.
/extensions
Extensions allow you to extend any registered block in your WordPress installation using a simple .json based API, which is similar to the block.json configuration. This includes core, third-party and blocks made with Blockstudio. All [field types]({{ site.url }}/documentation/attributes/field-types) can be added to any block, with the data being saved to the block's attributes. The complete feature set of attributes like [filtering]({{ site.url }}/documentation/attributes/filtering), [disabling]({{ site.url }}/documentation/attributes/disabling), [conditional logic]({{ site.url }}/documentation/attributes/conditional-logic) and [populating options]({{ site.url }}/documentation/attributes/populating-options) are available for extensions.
- #extension-types
  Extended values can now be utilized in more versatile ways: - class: Add a class using the attribute value to the block. - style: Add inline styles using the attribute value to the block. - attributes: Set any attribute value directly on the block, enhancing its functionality or accessibility. - data attributes: Use extension values to set specific data attributes, enabling more complex interactions and dynamic content adjustments.
- #setup
  Imagine the following scenario: you want to add a custom class select field to every core block. All you need to do is add this .json file anywhere in your block folder, and it will be automatically registered as an extension. { "$schema": "https://app.blockstudio.dev/schema/extend", "name": "core/*", "priority": 10, "blockstudio": { "extend": true, "attributes": [ { "id": "customColor", "type": "select", "label": "Custom color", "options": [ { "value": "#f00", "label": "Red" }, { "value": "#00f", "label": "Blue" } ], "set": [ { "attribute": "style", "value": "color: {attributes.customColor}" } ] } ] } } This will add a customColor field to every core block, allowing you to set the color of the block's text. Let's break down the configuration from top to bottom:
- #file-name
  Since there is no rendering template, an extension doesn't need a matching index file and thus doesn't need to be named block.json. This allows storing all extensions conveniently in a single folder.
- #schema
  Blockstudio provides a custom JSON schema for extension configurations: View Extension schema
- #name
  The name property of the configuration object defines which blocks should be extended. There are three options depending on your needs: - blockName: A single block name, e.g. core/paragraph. - [blockNameA, blockNameB]: An array of block names, e.g. ["core/paragraph", "core/heading"]. - core/*: A wildcard to extend all blocks of a certain type, e.g. core/*.
- #blockstudio-key
  Just like when using block.json for custom blocks, the blockstudio property has to be present in the configuration object with extend set to true.
- #position
  By default, extensions will render in its own tab in the block inspector. If you want to move the extensions to a different position, you can use the group property. The following values are currently available: - settings: The default position. - styles: The styles tab. - advanced: The advanced tab. { "$schema": "https://app.blockstudio.dev/schema/extend", "name": "core/*", "blockstudio": { "extend": true, "group": "styles", "attributes": [] } }
- #priority
  The priority property allows you to define the order in which extensions are rendered. Extensions with a higher priority will be rendered later. This is useful if you want an extension to appear before another one.
- #attributes
  For more information on how attributes work, please refer to the [attributes section]({{ site.url }}/documentation/attributes/field-types). The only thing you need to know about attributes inside extensions is the set property. It is used to apply the value of the attribute to one of the [types]({{ site.url }}/documentation/extensions#extension-types) of the block. For example, the following configuration will set the style attribute of the block to color: red or color: blue depending on the value of the select field. { "$schema": "https://app.blockstudio.dev/schema/extend", "name": "core/*", "blockstudio": { "extend": true, "attributes": [ { "id": "customColor", "type": "select", "label": "Heading color", "options": [ { "value": "#f00", "label": "Red" }, { "value": "#00f", "label": "Blue" } ], "set": [ { "attribute": "style", "value": "color: {attributes.customColor}" } ] } ] } }
- #getting-values
  Dot notation inside curly braces is used to get the value of an attribute. It is also possible to get nested values when attributes are not returning a single value, for example, when setting the return format to both on field types with options. { "attributes": [ { "id": "customColor", "type": "select", "label": "Heading color", "options": [ { "value": "#f00", "label": "Red" }, { "value": "#00f", "label": "Blue" } ], "returnFormat": "both", "set": [ { "attribute": "style", "value": "color: {attributes.customColor.value}" }, { "attribute": "data-color", "value": "{attributes.customColor.label}" } ] } ] } The example above will set the style attribute to color: #f00 or color:#00f and the data-color attribute to Red or Blue depending on the value. For now, only values from the current attribute can be used inside set definitions. The ability to use values from other attributes might be added in the future.
- #arrays
  When using arrays, the set property will be applied to every item in the array.
- #attributes-field
  When using the attributes field, there is no set property needed, as the field automatically maps the values to the attribute name and value
/general
- #introduction
  Blockstudio enables you to create custom WordPress blocks with nothing but PHP using the WordPress block.json format. It greatly simplifies the developer experience in regard to block registration, lazy loading assets, and custom fields.
- #core-focused
  There is no secret sauce. Blockstudio is built on top of core WordPress features and Gutenberg components. It is designed to be a lightweight abstraction layer that helps you get started with custom blocks quickly.
- #server-side-first
  When creating dynamic blocks using nothing but WordPress, there is duplication of logic between PHP and JS code. There are discussions about solving this issue, including hydrating blocks on the client side (not good for SEO) or introducing a JSX parser for PHP (complex). Blockstudio takes a different approach. You use PHP to write your block templates and sprinkle in interactivity like or using JSX-like tags. Inside the editor, those tags will be replaced with their React counterparts. On the frontend, the tags will be replaced with HTML content. This way, you get the best of both worlds: a server-side rendered block with great interactivity in the editor.
- #file-system-based
  While WordPress supports a file-based approach using the WPDefinedPath string type, it is also possible to link assets or templates from other destinations. Blockstudio doubles down on the file-system as the primary (and only) way of registering blocks. This decision was not made to restrict, but to set a block structure in place that can't be argued with. For example, if a style.css or script.js file is found in the same folder as a block.json, then you can be sure that it belongs to this exact block only.
- #no-setup
  Blockstudio just works. It is designed to remove friction when composing custom blocks and doesn't come in your way while doing so. Want to use Twig for your template? Simply rename the file extension. Need to include some CSS? Create a style.css file. Blockstudio will automatically enqueue it whenever the block is being used on your page, even when it is used outside the post_content with the [rendering function]({{ site.url }}/documentation/rendering-blocks). Do you have feature requests or questions? Message us.
/hooks
- javascript
  Besides PHP hooks, Blockstudio also provides JavaScript events to manipulate values and blocks inside the editor. Since events are tied to block names and attribute IDs, we will use namespace/my-block as the name in the following examples. Of course, you will need to replace it with your own block name.
- php
  Below you'll find a list of all available PHP hooks that can be used to extend or adjust the functionality of the plugin.
/initialization
Block templates will only be executed when the block is rendered. This is enough for most blocks; however, sometimes you need to execute code during an earlier stage of execution. For example, you may want to register a new post type or do some other type of setup unrelated to the block. To do this, you can add a PHP file that starts with init-, like init.php or init-post-types.php to your block directory. This file is executed during the init action. For more information on this specific stage, see the WordPress documentation. Any init.php file that is found within the block directory will be executed, regardless if it is part of a block context or not. This makes it perfect for organizing code snippets that are not related to any certain blocks.
/library
Since version 3.1.0, Blockstudio includes a library of prebuilt elements. Of course, these elements are making use of all the features that are available to Blockstudio users. In fact, the library is actively being used to dogfood our own product, helping us fast-track development and ensure a good developer experience for everyone. The library is a first step in making Blockstudio more available as a general collection of ready-to-use blocks for non developers, all the while being built with the most advanced block framework for WordPress. More blocks are actively being developed!
- #activating
- #blocks
/loading
Blockstudio blocks are dynamic, meaning that they must be rendered on the server to be displayed in Gutenberg. This rendering is facilitated by a fetch call to the Blockstudio block renderer. Upon first opening the editor, each block fetches its respective template, which results in multiple requests depending on the number of blocks present on the page. On some hosts, this can cause timeouts and errors while loading other essential assets needed for the editor to function properly.
- #disabling
  Rendering template loading can be disabled by setting the disableLoading key in block.json to true. A placeholder will be rendered in place of the block template. All field settings will still be available when opening the sidebar. { "name": "blockstudio/native", "title": "Native Block", "category": "text", "icon": "star-filled", "description": "Native Blockstudio block.", "blockstudio": { "blockEditor": { "disableLoading": true } } } }
/overrides
Blockstudio includes the possibility to override blocks on a very granular level. This can be useful for shared block libraries when you want to change the behavior of a block without having to create a new block from scratch.
- #block-json
  To get started, set the name of the block you want to override as the name key and set the override key to true. { "name": "blockstudio/my-block", "title": "My overridden block title", "blockstudio": { "override": true } } When the override property is set to true, the data from the new block.json will be merged with the data from the original block. This means that you can override any property of the original block.
- #attributes
  Attributes can either be overridden by id or added additionally. For example, let's imagine that we want to override the width attribute of a block and add a new height attribute. { "name": "blockstudio/my-block", "title": "My overridden block title", "blockstudio": { "override": true, "attributes": [ { "id": "width", "type": "number", "default": 280, "label": "Override width" }, { "id": "height", "type": "number", "default": 280, "label": "New height" } ] } } When an attribute with the same id is found, the data will be merged with the original attribute. Attributes which are not found will be added to the block. Important: When overriding attributes, you have to provide the type of the original attribute, even if it stays the same.
- #complex-structures
  When overriding attributes with complex structures (repeaters, groups, tabs, etc.), you have to provide the full structure of the attribute to the point of the item that should be overridden. { "name": "blockstudio/my-block", "blockstudio": { "override": true, "attributes": [ { "id": "tabs", "type": "tabs", "tabs": [ { "id": "tab1", "attributes": [ { "key": "group1", "type": "group", "title": "Group", "attributes": [ { "id": "text", "type": "text", "label": "Override text" } ] } ] }, { "id": "tab2", "title": "Override tab", "attributes": [ { "id": "group", "type": "group", "title": "Group ID", "attributes": [ { "id": "text", "type": "text", "label": "Override text" } ] } ] } ] } ] } }
- #assets
  Asset files will be replaced when the file name matches. For example, if a style.css file exists in the original block, it will be replaced by the style.css file in the overriding block. Files with names that do not match the original block will be added to the block.
- #rendering-template
  Rendering templates can be overridden by providing a new template file, so either index.php or index.twig.
- #twig-blocks
  Twig templates can be overridden on a more granular level using the block feature in Twig. Let's imagine the following rendering template for a fictional image block:
  Images:
  
  Instead of replacing the whole template, we can use Twigs extends feature to override certain parts of the template while keeping the rest intact. {% block image %} <figure> <img src="{{ image.url }}" class="image" /> <figcaption>{{ image.caption }}</figcaption> </figure> {% endblock %}
/post-meta
Since block templates are just normal PHP files, you can use any PHP code you want in them. However, since blocks don't have access to the global $post variable inside the editor, get_the_ID() and other functions that depend on the variable will only work on the frontend. Blockstudio provides four different ways to access the current post ID in the editor and the frontend. echo $post_id; echo $postId; echo $block['postId']; echo $b['postId']; {{ post_id }}; {{ postId }}; {{ block.postId }}; {{ b.postId }};
- #getting-post-meta
  All common custom field plugins and WordPress itself provide the possibility to access post meta using a post ID.
- #acf
  echo get_field('field_name', $post_id); {{ fn('get_field', 'field_name', postId) }};
- #metabox
  echo rwmb_get_value('field_id', null, $post_id); {{ fn('rwmb_get_value', 'field_id', postId) }};
- #refreshing-blocks
  By default, blocks won't be refreshed when you save or update a post. Thus, old data might be displayed in the editor after saving. To fix this, you can use the refreshOn key inside your block.json to tell Blockstudio to refresh the block when a post is saved. { "name": "blockstudio/native", "title": "Native Block", "category": "text", "icon": "star-filled", "description": "Native Blockstudio block.", "blockstudio": { "refreshOn": [ "save" ] } }
/preview
Gutenberg allows previewing blocks when hovering over the block in the fixed block inserter. To enable the preview of blocks made with Blockstudio, simply set the example key to an empty object. { "name": "blockstudio/native", "title": "Native Block", "category": "text", "icon": "star-filled", "description": "Native Blockstudio block.", "example": {}, "blockstudio": true }
- #custom-data
  It is also possible to provide structured data in the example key, so any custom attributes are correctly being rendered. { "name": "blockstudio/native", "title": "Native Block", "category": "text", "icon": "star-filled", "description": "Native Blockstudio block.", "example": { "attributes": { "title": "This title will be shown in the preview" } }, "blockstudio": true }
  
  {{ a.title }}
- #innerblocks
  If your block relies on InnerBlocks, it is possible to provide a template for the InnerBlocks. { "name": "blockstudio/native", "title": "Native Block", "category": "text", "icon": "star-filled", "description": "Native Blockstudio block.", "example": { "innerBlocks": [ { "name": "core/paragraph", "attributes": { "content": "This is the default InnerBlocks block." } } ] }, "blockstudio": true }
/registration
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 that contain a block.json file with a blockstudio key will be registered.
- #block-json
  { "name": "blockstudio/native", "title": "Native Block", "category": "text", "icon": "star-filled", "description": "Native Blockstudio block.", "blockstudio": true }
- #template
  So far, the custom block is not going to be registered since it is missing a template. 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.
  My first native block.
- #twig
  Twig is a flexible, fast, and secure template engine for PHP. It allows developers to write concise and readable code in templates, enhancing productivity and maintainability. Twig supports a variety of features designed to make templating both powerful and straightforward, making it ideal for projects that require robust, reusable templates.
- #conditional-logic
  Blocks can be registered conditionally using the conditions key. It supports all the global variables which are also available for attributes. See all conditions The following example will only register the block if the current post type is a page: { "blockstudio": { "conditions": [ [ { "type": "postType", "operator": "==", "value": "page" } ] ], } }
- #custom-icon
  Custom SVGs icons for blocks can be registered like so: { "blockstudio": { "icon": "" } } WordPress doesn't allow for custom SVG icons inside its own block.json icon key, only Dashicons IDs are allowed here.
- #html
  Blockstudio is using a React element parser to render the icon element, so it is possible to use HTML inside the icon string. { "blockstudio": { "icon": "
  :-)
  " } }
- #custom-paths
  By default, Blockstudio will recursively look through the blockstudio folder inside your current theme or child theme for blocks. You can change that behaviour in two ways.
- #filter
  // 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'; });
- #instances
  If the above options are not enough, it is possible to initiate the Blockstudio\\Build class on various folders of your choice: add_action('init', function () { Blockstudio\\Build::init([ 'dir' => get_template_directory() . '/client-blocks' ]); });
- #filter-metadata
  Metadata can be filtered before the block is being registered using the blockstudio/block/meta filter: The example above is being used internally to give all Blockstudio library elements the same icon.
/rendering
With Gutenberg becoming the prominent instrument in creating easily editable websites for clients, it makes sense to create all necessary website areas as blocks. While this approach will cater to most, advanced users and specific use cases might need to use those existing blocks outside the editor. Blockstudio provides two specific functions for exactly this use case: - bs_render_block: immediately renders the block to the page (no "echo "needed) - bs_block: needs an "echo" to be rendered to the page. This function is useful when nesting blocks. All Blockstudio specific features like inline styles, scripts, and scoped styles are supported when using the render functions.
- #without-data
  In its simplest form, the function accepts a single value which is the ID of the block that should be rendered on the page. bs_render_block('blockstudio/cta');
- #with-data
  To render the block with custom data, an array needs to be used in place of a single value for the first parameter. The value in the data key will be passed to the $attributes and $a variable inside your block template. bs_render_block([ 'id' => 'blockstudio/cta', 'data' => [ 'title' => 'My title', 'subtitle' => 'My subtitle', ], ]);
- #nesting
  Blocks can be nested within each other using the bs_block function in combination with the powerful $content variable inside your block templates.
  
  echo bs_block([ 'id' => 'blockstudio/cta', 'data' => [ 'title' => 'My title', 'subtitle' => 'My subtitle', ], 'content' => bs_block([ 'id' => 'blockstudio/cta', 'data' => [ 'text' => 'Button Text', ], ]) ]); The button block will be rendered in place of the $content variable inside the block template.
- #multiple-slots
  It is also possible to create multiple content slots by simply making the $content variable an associative array and calling it approriate keys in the bs_block function.
  
  echo bs_block([ 'id' => 'blockstudio/cta', 'data' => [ 'title' => 'My title', 'subtitle' => 'My subtitle', ], 'content' => [ 'beforeContent' => bs_block([ 'id' => 'blockstudio/badge', 'data' => ['text' => 'Before Content'], ]), 'afterContent' => bs_block([ 'id' => 'blockstudio/cta', 'data' => ['text' => 'Button Text'], ]) ] ]);
/schema
To improve development with autocomplete and validation in your IDE, Blockstudio introduces its own schema: View Blockstudio schema The Blockstudio schema is an (always up-to-date) copy of the WordPress core block.json schema with an additional blockstudio property that houses all plugin features like field schemas without interfering with potential future core properties
- #add-to-json
  Simply add a $schema key with a value of https://app.blockstudio.dev/schema to your block.json and your IDE should start to give you hints about Blockstudio specific properties. { "$schema": "https://app.blockstudio.dev/schema", "name": "blockstudio/native", "title": "Native Block", "category": "text", "icon": "star-filled", "description": "Native Blockstudio block.", "blockstudio": true }
/settings
Blockstudio includes a powerful settings API, that allows setting options via a blockstudio.json file inside your theme folder and/or filters. Additionally, allowed users are able to change the settings visually inside the admin area.
- #json
  If a blockstudio.json file is present inside your theme folder, it will be used to set the default options for the current site. A JSON schema is available to validate the file and help with autocompletion when used in an IDE. The following properties are available. { "$schema": "https://app.blockstudio.dev/schema/blockstudio", "users": { "ids": [], "roles": [] }, "assets": { "enqueue": true, "minify": { "css": false, "js": false }, "process": { "scss": false } }, "editor": { "formatOnSave": false, "assets": [], "markup": false }, "library": false }
- #filters
  Alternatively you can use the blockstudio/settings/${setting} filter to set options via PHP for more flexibility. add_filter('blockstudio/settings/assets/enqueue', '__return_false'); add_filter('blockstudio/settings/editor/formatOnSave', '__return_true'); add_filter('blockstudio/settings/library', '__return_true'); Options set via the blockstudio/settings/${setting} filter will override the ones set via the blockstudio.json file. Both methods can be used together.
- #admin
  Allowed users from the blockstudio/settings/users/ids and blockstudio/settings/users/roles filters are able to change the settings visually inside the admin area. If the Save as JSON checkbox is checked, the settings will be saved to the JSON file, otherwise they will be saved to the database into the options table. Settings set via filters will be grayed out and disabled inside the admin area.
/transforms
The Block Transforms API allows you to define ways in how to transform blocks. Blockstudio currently supports three different types: - block to block: transform a block into another block - enter: insert a block when the user enters text and presses Enter - prefix: insert a block when the user enters text and presses Space
- #block-to-block
  Block to block transforms allow you to transform a block into another block. { "$schema": "https://app.blockstudio.dev/schema", "name": "blockstudio/transforms", "title": "Native Transforms", "icon": "star-filled", "description": "Native Blockstudio Transforms.", "blockstudio": { "transforms": { "from": [ { "type": "block", "blocks": [ "blockstudio/transforms-2", "blockstudio/transforms-3" ] } ] }, "attributes": [ { "id": "text", "type": "text", "label": "Text" } ] } } When transforming into the new block, the attributes of the old block will be passed to the new block. In the example above, the text attribute will be passed to the new block. The same goes for all InnerBlocks content. It is important to note that the attribute types have to be the same for the block being transformed into and the block being transformed from. For example, if the block being transformed into has an attribute with the ID of text but the type of number, it won't appear in the transform list, as this would cause a type mismatch and rendering error. The number of attributes between the two blocks doesn't have to be the same.
- #enter
  Enter transforms allow you to insert a block when the user types certain content and then presses the Enter key. { "blockstudio": { "transforms": { "from": [ { "type": "enter", "regExp": "/^-{3,}$/" } ] } } } In the example above, the block will be inserted when the user types three or more dashes (-) and then presses Enter.
- #prefix
  Prefix transforms allow you to insert a block when the user types certain content and then presses the Space key. { "blockstudio": { "transforms": { "from": [ { "type": "prefix", "regExp": "???" } ] } } } In the example above, the block will be inserted when the user types three question marks (?) and then presses Space.
/variations
The Block Variation API allows you to register custom variations for existing blocks. Let's imagine a block that should have two different variations depending on the value of a simple select field. { "$schema": "https://app.blockstudio.dev/schema", "name": "blockstudio/variations", "title": "Native Variation", "description": "Native Blockstudio Variation block.", "icon": "star-filled", "variations": [ { "name": "variation-2", "title": "Native Variation 2", "description": "Native Blockstudio Variation block 2.", "attributes": { "select": { "value": "variation-2" } } } ], "blockstudio": { "attributes": [ { "id": "select", "type": "select", "label": "Select", "options": [ { "value": "variation-1", "label": "Variation 1" }, { "value": "variation-2", "label": "Variation 2" } ], "default": { "value": "variation-1" } } ] } } The above will create three blocks in the inserter, the main one, and two variations.
- #hiding-attributes
  Attributes will automatically render the appropriate input in the sidebar. Since variation blocks depend on specific attribute values, you might want to hide those fields from the sidebar. To do so, you can use the hidden option. { "blockstudio": { "attributes": [ { "id": "select", "type": "select", "label": "Select", "hidden": true, "options": [ { "value": "variation-1", "label": "Variation 1" }, { "value": "variation-2", "label": "Variation 2" } ] } ] } }

Components - InnerBlocks

Basic usage

Properties

allowedBlocks

tag

template

templateLock

renderAppender

useBlockProps

Context

Registering

Templates

Frontend wrapper

Return early

Dynamic templates

My block

My block

My block

Scope me!

The block is aligned:

The block is aligned:

The block is aligned: {{ block.align }}

The block is aligned: {{ b.align }}

>

{{ a.message }}

Hello

>

{{ a.message }}

Hello

{{ a.message }}

Hello

{{ a.message }}

Hello

{{ attributes.message }}

{{ a.message }}

{{ a.message }}

{{ container['full-width'] ? 'is full width' : 'no full width' }}

This is the data of current element inside the loop:

This is the data the current post:

This is the data of current element inside the loop: {{ block.context.postId }} {{ block.context.postType }}

This is the data the current post: {{ block.postId }} {{ block.postType }}

Images:

{{ a.title }}

My first native block.

My block

My block

My block

Scope me!

The block is aligned:

The block is aligned:

The block is aligned: {{ block.align }}

The block is aligned: {{ b.align }}

>

{{ a.message }}

Hello

>

{{ a.message }}

Hello

{{ a.message }}

Hello

{{ a.message }}

Hello

{{ attributes.message }}

{{ a.message }}

{{ a.message }}

{{ container['full-width'] ? 'is full width' : 'no full width' }}

This is the data of current element inside the loop:

This is the data the current post:

This is the data of current element inside the loop: {{ block.context.postId }} {{ block.context.postType }}

This is the data the current post: {{ block.postId }} {{ block.postType }}

Images:

{{ a.title }}

My first native block.