Native blocks

Version 2.4.0 introduces a highly requested feature: custom blocks using WordPress core. Instead of relying on an additional plugin like Advanced Custom Fields or Metabox, users are now able to create blocks with custom fields using Blockstudio by itself.

Internally, Blockstudio native blocks are using Gutenberg components like TextControl or RangeControl for its fields, ensuring that users benefit from the constant updates made to the Gutenberg project.


Traditionally, Blockstudio blocks have been registered using file headers . While this approach allows for clean single block components, new block properties (added by WordPress) have to be added to the plugin manually.

By adopting the block.json standard of registering block types, native blocks will move together with WordPress core and support new features without requiring plugin updates.

Registering blocks via file headers for ACF and MB blocks will be supported for the foreseeable future.

Arrow Forward Circle

ACF is also preparing an upgrade to the common block.json standard. (which Blockstudio will support once it is stable)


To improve development with autocomplete and validation in your IDE, Blockstudio introduces its own schema:

View Blockstudio schema

blockstudio schema

The Blockstudio schema is an (always up-to-date) copy of the WordPress core block.json schema with two differences:

  • Attributes are removed (see how to register custom attributes for more information)
  • Additional blockstudio property that houses all plugin features like field schemas without interfering with potential future core properties

Registering blocks


Native blocks are registered like so:

Blockstudio\Build::init( [ 'dir' => get_template_directory() . '/native-blocks', 'type' => 'native' ] );


To register native blocks, you will need two files in a given sub folder of the directory that was passed to the Build::init function.

  • block.json: the place where all your metadata about the block is stored.
  • index.php or index.twig: this file will be rendered inside the editor and on the frontend.
{ "$schema": "", "apiVersion": 2, "name": "blockstudio/native", "title": "Native Block", "category": "text", "icon": "star-filled", "description": "Native Blockstudio block.", "keywords": [ "block", "native" ], "version": "1.0.0", "textdomain": "blockstudio", } <h1>My first native block.</h1>

And that's it! You've successfully created your first native block with Blockstudio. Please note that the id property needs to be unique.


Of course, blocks without dynamic data are kinda boring! Attributes allow you to add data to your blocks and are comparable from 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": "", "apiVersion": 2, "name": "blockstudio/native", "title": "Native Block", "category": "text", "icon": "star-filled", "description": "Native Blockstudio block.", "keywords": [ "block", "native" ], "version": "1.0.0", "textdomain": "blockstudio", "supports": { "align": true }, "blockstudio": { "attributes": [ { "id": "message", "type": "text", "label": "My message" } ] } }

And that's it! You've just registered your first custom attribute:

text field


Inside template files, all attributes can be accessed using the $attibutes or $a variables and the respective ID of the field.

// index.php <h1><?php echo $attributes['message']; ?></h1> <h1><?php echo $a['message']; ?></h1> // index.twig <h1>{{ attributes.message }}</h1> <h1>{{ a.message }}</h1>

Attribute values render false if the field is empty or no option has been selected.

<?php if ($a['message']) : ?> <h1><?php echo $a['message']; ?></h1> <?php endif; ?>

Block attributes

The $attibutes 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.

// index.php <h1>The block is aligned: <?php echo $block['align']; ?></h1> <h1>The block is aligned: <?php echo $b['align']; ?></h1> // index.twig <h1>The block is aligned: {{ block.align }}</h1> <h1>The block is aligned: {{ b.align }}</h1>

Field types


group field

Group multiple fields in an (optionally) collapsible container.


title: string

opened: boolean

icon: string

initialOpen: boolean

attributes: array
Accepts all other field types besides another group.


{ "blockstudio": { "attributes": [ { "id": "controls", "type": "group", "label": "My group", "attributes": [ { "id": "message", "type": "text", "label": "My message" } ] } ] } }

To access attributes inside groups, simply prepend the group ID to the inner attribute ID.

<h1><?php echo $attributes['group_message']; ?></h1> <h1><?php echo $a['group_message']; ?></h1>


text field

Enter and edit a single line of text.


default: string


textarea field

Enter and edit multiple lines of text.


default: string

rows: number


number field

Enter and edit a number.


default: number

dragDirection: string

dragThreshold: number

hideHTMLArrows: boolean

isShiftStepEnabled: boolean

required: boolean

max: number

min: number

shiftStep: number

step: number


range field

Set a numerical value between two points.


default: number

beforeIcon: string

afterIcon: string

allowReset: boolean

initialPosition: number

isShiftStepEnabled: boolean

marks: object (label: string, value: number)

max: number

min: number

railColor: string

resetFallbackValue: number

showTooltip: boolean

shiftStep: number

step: number

trackColor: string

withInputField: boolean


toggle field

Toggle between a true or false value.


default: boolean


checkbox field

Choose one or multiple options from a set.


default: boolean

options: object (label: string, value: string)


select field

Choose a single or multiple options from a dropdown list.


default: string

multiple: boolean

options: object (label: string, value: string, disabled: boolean)


radio field

Choose one option from a set.


default: string

options: object (label: string, value: string)


combobox field

An enhanced dropdown list that also allows you to search for items.


default: string

options: object (label: string, value: string)


color field

Choose a color and display a palette of colors.


default: string

options: object (name: string, value: string, slug: string)

clearable: boolean

disableCustomColors: boolean


gradient field

Choose a gradient and display a palette of gradients.


default: string

options: object (name: string, value: string, slug: string)

clearable: boolean

disableCustomGradients: boolean