Skip to content

Custom blocks in 3 files

No JavaScript, no build step, no boilerplate.

Define fields in JSON

Add a blockstudio key to block.json. Define attributes with types such as text, toggle, and color. Blockstudio generates the editor UI automatically, with 27 field types from text inputs to repeaters and code editors, plus field types you register yourself.

Full JSON Schema support gives autocomplete and validation in VS Code, PhpStorm, and every compatible editor.

Every field can set a default for new blocks and a fallback that the template receives while the field is empty.

block.json
{
  "name": "starter/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading" },
      { "id": "showCta", "type": "toggle", "label": "Show CTA" },
      { "id": "background", "type": "color", "label": "Background" }
    ]
  }
}

3-file workflow

block.json for fields, a template for markup, and an optional stylesheet.

React in PHP

RichText, InnerBlocks, and useBlockProps work directly in PHP, Twig, or Blade.

SCSS and Tailwind

Use CSS, SCSS, or Tailwind. SCSS supports import paths and a shared prelude, and editing a nested partial recompiles every file that imports it.

27 field types

Text, color, image, repeater, select, code editor, and more, configured in JSON.

JSON Schema

Autocomplete and validation in VS Code, PhpStorm, and compatible editors.

Three template languages

PHP, Twig, and Blade share the same variables and components.

npm imports

Import packages in script.js; local in production and CDN-backed in the editor.

Interactivity API

Enable the WordPress Interactivity API with one flag.

React components in PHP templates

Use <RichText /> for inline editing and static frontend HTML, <InnerBlocks /> for child blocks, and useBlockProps for the wrapper, all in one template.

In the editor these become real React components. On the frontend they render as server-side HTML, with no JavaScript shipped to visitors.

index.php
<div useBlockProps class="container">
  <RichText
    class="text-xl font-semibold"
    tag="h1"
    attribute="headline"
    placeholder="Enter headline"
  />

  <?php if ($a['showCta']): ?>
    <a href="<?= esc_url($a['ctaUrl']) ?>">
      <?= esc_html($a['ctaLabel']) ?>
    </a>
  <?php endif; ?>

  <InnerBlocks class="mt-4 p-4 border" />
</div>

Write in PHP, Twig, or Blade

Use the template language you know. PHP works out of the box, Twig runs once Timber is installed, and Blade runs on illuminate/view 8 to 12 through Blockstudio\Blade_Renderer. The variables, components, and behavior stay the same.

$a (attributes), $b (block), $c (context), and $innerBlocks are available in every language.

Twig templates also receive the full Timber context. Blade renders pages, patterns, and Site Editor templates too. The older jenssegers/blade wrapper fails with illuminate/view 10 and later, so use Blade_Renderer instead.

index.twig
<div useBlockProps class="card">
  <RichText tag="h2" attribute="title" placeholder="Card title" />
  {% if a.image %}
    <img src="{{ a.image.url|esc_url }}"
      alt="{{ a.image.alt|esc_attr }}" />
  {% endif %}
  <div class="card__body">{{ a.description|esc_html }}</div>
  <InnerBlocks allowedBlocks='["core/button"]' />
</div>

Conditional logic and dynamic options

Show and hide fields with operators including ==, !=, includes, empty, and comparisons. Combine conditions with OR logic.

Options can depend on another field. Put {attributes.post_type.value} into the populate arguments and the list reloads when that field changes. Add fetch: true to search posts as the editor types.

Share one option list across blocks with type: custom and the blockstudio/blocks/attributes/populate filter, and register your own global conditions, such as a purchase check, through blockstudio/blocks/conditions.

block.json
{
  "name": "starter/posts",
  "title": "Posts",
  "blockstudio": {
    "attributes": [
      {
        "id": "post_type",
        "type": "select",
        "label": "Post type",
        "options": [
          { "value": "page", "label": "Pages" },
          { "value": "post", "label": "Posts" }
        ]
      },
      {
        "id": "selected_post",
        "type": "select",
        "label": "Post",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": { "post_type": "{attributes.post_type.value}" }
        }
      },
      {
        "id": "style",
        "type": "select",
        "label": "Style",
        "populate": { "type": "custom", "custom": "cardStyles" },
        "conditions": [[
          { "type": "purchasedProduct", "operator": "==", "value": "yes" }
        ]]
      }
    ]
  }
}

Repeaters that stay manageable

Set min and max, start new blocks with default rows, and collapse existing rows with minimized. textMinimized labels a collapsed row with one of its own fields, such as a name.

Rows accept every field type except tabs, including nested repeaters. A condition inside a row checks a field outside it with "context": "main", and <RichText /> and <MediaPlaceholder /> edit a single row when their attribute points at repeaterId[index].fieldId.

block.json
{
  "name": "starter/team",
  "title": "Team",
  "blockstudio": {
    "attributes": [
      {
        "id": "members",
        "type": "repeater",
        "label": "Team members",
        "min": 1,
        "max": 12,
        "minimized": true,
        "textMinimized": { "id": "name", "fallback": "Team member" },
        "attributes": [
          { "id": "name", "type": "text", "label": "Name" },
          { "id": "bio", "type": "richtext", "label": "Bio" }
        ]
      }
    ]
  }
}

Reusable field sets

Define a group of fields once in a field.json and reference it from any block with "type": "custom/cta". The fields are inlined, so templates read them like any other attribute.

Use the same set twice with an idStructure such as hero_{id}, and change labels, defaults, or conditions per block with overrides. The block field type does the same with a whole block: it expands that block’s fields inline and returns its rendered HTML.

fields/cta/field.json
{
  "name": "cta",
  "title": "Call to action",
  "attributes": [
    { "id": "label", "type": "text", "label": "Button label", "default": "Learn more" },
    { "id": "url", "type": "link", "label": "Button URL" }
  ]
}

ES modules without a build step

Add script.js and it loads as an ES module. Import npm packages with the npm: prefix and Blockstudio downloads them locally for production.

The editor gets instant preview while the frontend uses local modules with zero external dependency, enqueued only once.

Stylesheets import the same way. import "npm:swiper@11.0.0/swiper.min.css" downloads the file and enqueues it once per version, even when several blocks use it.

script.js
import Swiper from "npm:swiper@11.0.0";
import "npm:swiper@11.0.0/swiper.min.css";

for (const el of document.querySelectorAll(".swiper")) {
  new Swiper(el, {
    slidesPerView: 3,
    spaceBetween: 20,
    loop: true,
  });
}

Block tags beyond templates

Map a short prefix to a namespace in blockstudio.json, or one tag to one block with an alias filter, and <acme-card> renders acme/card. Turn on blockTags.enabled to render tags in post content and widgets, limited by allow and deny patterns.

data-* attributes reach the block’s root element, and html-* attributes arrive there without the prefix. Add your own tag builders with blockstudio/block_tags/builders, and rewrite shorthands to the portable <bs:acme-card> spelling with the migrate-block-tags command.

blockstudio.json
{
  "blockTags": {
    "enabled": true,
    "prefixes": {
      "acme": ["acme"],
      "ui": ["acme-ui"]
    },
    "deny": ["acme-ui/admin-*"]
  }
}

Custom field types

Register your own field control and use it like a built-in field.

Block islands

Cache the whole page and render one block in the visitor’s request.

Conditional registration

Register a block only for a post type, user role, or other global condition, or skip it while a plugin or plugin version it needs is missing.

Post meta and options

Store values in post meta or options alongside block attributes.

Conditional logic

Show fields based on values using equality, inclusion, emptiness, and comparisons.

Dynamic populations

Populate choices from posts, users, terms, functions, or APIs.

Overrides

Set override: true with a shared block’s name to merge attributes by id, replace assets with matching file names, and swap the template. Twig templates can override single blocks with extends.

Variations

Declare variations in block.json that preset field values, and hide the field that drives them with hidden.

Components

Set component: true for a block that renders only from PHP or block tags. It keeps fields, templates, assets, and Tailwind but never appears in the inserter.

InnerBlocks rules

Allow blocks with namespace/*, category: and @theme tokens, switch the inner template from a select option, and drop the wrapper on the frontend with a filter.

Code field assets

A code field with asset: true turns editor input into CSS, SCSS, or JavaScript for that block, scoped to the instance through %selector%.

Assets by file name

*.view.js loads on the frontend only, and the global-, admin-, and block-editor- prefixes load a file on every page, in wp-admin, or in the block editor.

Icons and block folders

Give a block a custom SVG or HTML icon, move discovery with the blockstudio/path filter, and add folders with Blockstudio\Build::init().

ACF and Meta Box values

Templates receive $post_id, so get_field() and rwmb_get_value() read the edited post, and refreshOn reloads the preview after saving.

Query Loop context

Inside a Query Loop, $block[‘context’][‘postId’] follows the current item while $block[‘postId’] stays the post being viewed.

WPML

wp bs wpml config writes the wpml-config.xml that marks text fields translatable, and images stored in fields join WPML translation jobs with their alt texts and captions.

Plus

The official extension kit

Premium site templates, AI system instructions, and a private Discord community. One-time purchase, lifetime updates.

  • 500+ site templates
  • AI system instructions
  • Lifetime updates
  • Private Discord community