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.
{
"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.
<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.
<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><div useBlockProps class="card">
<RichText tag="h2" attribute="title" placeholder="Card title" />
@if ($a['description'])
<div class="card__body">{{ $a['description'] }}</div>
@endif
<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.
{
"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" }
]]
}
]
}
}add_filter('blockstudio/blocks/attributes/populate', function ($options) {
$options['cardStyles'] = [
['value' => 'light', 'label' => 'Light'],
['value' => 'dark', 'label' => 'Dark'],
];
return $options;
});
add_filter('blockstudio/blocks/conditions', function ($conditions) {
$conditions['purchasedProduct'] = user_has_purchased(123) ? 'yes' : 'no';
return $conditions;
});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.
{
"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" }
]
}
]
}
}<div useBlockProps class="team">
<?php foreach ($a['members'] as $index => $member): ?>
<article>
<h3><?= esc_html($member['name']) ?></h3>
<RichText
tag="p"
attribute="members[<?= $index ?>].bio"
placeholder="Short bio"
/>
</article>
<?php endforeach; ?>
</div>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.
{
"name": "cta",
"title": "Call to action",
"attributes": [
{ "id": "label", "type": "text", "label": "Button label", "default": "Learn more" },
{ "id": "url", "type": "link", "label": "Button URL" }
]
}{
"name": "starter/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "type": "custom/cta", "idStructure": "primary_{id}" },
{
"type": "custom/cta",
"idStructure": "secondary_{id}",
"overrides": {
"label": { "default": "Contact us" }
}
},
{
"id": "card",
"type": "block",
"block": "starter/card",
"idStructure": "card_{id}"
}
]
}
}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.
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.
{
"blockTags": {
"enabled": true,
"prefixes": {
"acme": ["acme"],
"ui": ["acme-ui"]
},
"deny": ["acme-ui/admin-*"]
}
}<div useBlockProps class="acme-features">
<acme-card
title="Fast"
text="Rendered on the server."
data-track="card"
/>
<ui-button label="Get started" href="/start" html-id="start" />
</div>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.
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