The block framework
for WordPress
The fastest way to build custom blocks. Define fields in JSON, write templates in PHP, Twig, or Blade. No build step required.
composer require blockstudio/blockstudioBlocks
Create custom blocks with JSON and PHP, Twig, or Blade templates. 30+ field types, no build step.
Pages
Build full WordPress pages as file-based templates that automatically sync to native blocks.
Patterns
Define reusable block patterns as template files, registered automatically in the inserter.
Extensions
Add custom fields to any block, core, third-party, or your own, with a single JSON file.
Field Types
30+ built-in types including repeaters, conditional logic, color pickers, code editors, and media.
Asset Processing
SCSS compilation, ES modules, scoped styles, and automatic minification, all by naming convention.
JSON Schema
Full IDE autocomplete and validation for block, extension, and settings configurations.
Templating
Write templates in PHP, Twig, or Blade with scoped assets, nested InnerBlocks, and template variables.
Blockstudio deeply extends the core way of building blocks. JSON definitions, PHP templates, scoped assets. Nothing more than files, ready for the agents that will build what's next.
Custom blocks in 3 files
Define fields in block.json, render them in a template, style with CSS or SCSS. No JavaScript, no build step, no boilerplate.
{
"name": "starter/hero",
"title": "Hero",
"blockstudio": {
"attributes": {
"heading": {
"type": "text"
},
"showCta": {
"type": "toggle",
"label": "Show CTA"
},
"background": {
"type": "color"
}
}
}
}<section
style="background: <?= $a['background'] ?>"
>
<h1><?= $a['heading'] ?></h1>
<?php if ($a['showCta']): ?>
<a href="/contact">Get Started</a>
<?php endif; ?>
<InnerBlocks />
</section>section {
padding: 4rem 2rem;
h1 {
font-size: 3rem;
font-weight: 700;
}
a {
display: inline-block;
padding: 0.75rem 1.5rem;
background: currentColor;
}
}React features, PHP templates
Blockstudio brings the best of both worlds. Native WordPress editor components like RichText and InnerBlocks, accessible directly in your PHP templates. No JavaScript, no build step.
All inside the same file
Use <RichText /> for inline editing in the block editor and static HTML on the frontend. <InnerBlocks /> for nested child blocks. And useBlockProps to mark the block wrapper. All from a single template file.
Blockstudio handles the editor integration automatically. In the editor, these become real React components. On the frontend, they render as plain server-side HTML.
<div useBlockProps class="container">
<RichText
class="text-xl font-semibold"
tag="h1"
attribute="richtext"
placeholder="Enter headline"
/>
<?php if ($a['showCta']): ?>
<a href="<?= $a['ctaUrl'] ?>">
<?= $a['ctaLabel'] ?>
</a>
<?php endif; ?>
<InnerBlocks class="mt-4 p-4 border" />
</div>Write templates in PHP, Twig, or Blade
Use the templating language you already know. All three share the same variables, components, and features. No JavaScript required.
Same variables, any language
Access attributes via $a, block data via $b, and parent context via $c. Use flags like $isEditor to tailor output per environment.
Use features like <InnerBlocks />, <RichText />, and <MediaPlaceholder /> directly in your templates, without writing any JavaScript.
<section class="hero">
<h1><?= $a['heading'] ?></h1>
<p><?= $a['description'] ?></p>
<?php if ($a['showCta']): ?>
<a href="<?= $a['ctaUrl'] ?>">
<?= $a['ctaLabel'] ?>
</a>
<?php endif; ?>
<?php foreach ($a['features'] as $feature): ?>
<div class="feature">
<h3><?= esc_html($feature['title']) ?></h3>
<p><?= wp_kses_post($feature['text']) ?></p>
</div>
<?php endforeach; ?>
<InnerBlocks />
</section><section class="hero">
<h1>{{ a.heading|upper }}</h1>
<p>{{ a.description|truncate(120) }}</p>
{% if a.showCta %}
<a href="{{ a.ctaUrl }}">
{{ a.ctaLabel }}
</a>
{% endif %}
{% for feature in a.features %}
<div class="feature">
<h3>{{ feature.title|title }}</h3>
<p>{{ feature.text|striptags }}</p>
</div>
{% endfor %}
<InnerBlocks />
</section><section class="hero">
<h1>{{ Str::upper($a['heading']) }}</h1>
<p>{{ Str::limit($a['description'], 120) }}</p>
@if($a['showCta'])
<a href="{{ $a['ctaUrl'] }}">
{{ $a['ctaLabel'] }}
</a>
@endif
@foreach($a['features'] as $feature)
<div class="feature">
<h3>{{ $feature['title'] }}</h3>
<p>{{ $feature['text'] }}</p>
</div>
@endforeach
<InnerBlocks />
</section>Full pages, defined in code
Create complete WordPress pages from template files. HTML maps to core blocks automatically. Blockstudio keeps the editor in sync.
Write HTML, get blocks
Standard elements like <h1>, <p>, and <ul> map to core blocks automatically. Use the <block> tag for everything else. Any block name, any attributes.
Define entire page layouts in your codebase. Blockstudio parses your templates and creates real WordPress pages with real blocks , fully editable in the block editor.
<div>
<h1 blockEditingMode="contentOnly">About Us</h1>
<p>We build tools for WordPress developers.</p>
<img src="/team.jpg" alt="Our team" />
</div>
<block name="core/columns">
<block name="core/column">
<h2>Our Mission</h2>
<p>Making block development fast and simple.</p>
</block>
<block name="core/column">
<block name="blockstudio/features" layout="grid">
<h2>Our Stack</h2>
<ul>
<li>PHP and WordPress</li>
<li>Zero JavaScript</li>
</ul>
</block>
</block>
</block>Automatic sync
Pages sync to WordPress on every admin load. Change your template, the editor updates instantly.
Template locking
Lock the entire page so clients can only edit content, not structure. Perfect for landing pages and marketing sites.
Keyed blocks
Assign keys to individual blocks so user edits persist across template updates. Sync structure, keep content.
Version controlled
Pages live in your theme or plugin as files. Track changes in Git, deploy across environments, review in PRs.
Reusable patterns from template files
Define block patterns as template files. Same HTML syntax as pages, registered automatically in the block inserter.
Template files, not registration code
Create a folder with a pattern.json and a template file. Blockstudio registers the pattern automatically, no register_block_pattern() boilerplate.
Patterns are inserted as real, editable blocks. Users get a starting layout they can fully customize, while you maintain the templates in version control.
<div>
<h2>Pricing</h2>
<p>Simple, transparent pricing.</p>
<block name="core/columns">
<block name="core/column">
<h3>Starter</h3>
<p>For small teams getting started.</p>
<block name="core/button" url="/signup">
Get Started
</block>
</block>
<block name="core/column">
<h3>Pro</h3>
<ul>
<li>Priority support</li>
<li>Custom integrations</li>
</ul>
<block name="core/button" url="/signup?plan=pro">
Go Pro
</block>
</block>
</block>
</div>Same syntax as pages
Patterns use the same HTML parser. Standard HTML maps to core blocks, the <block> tag handles everything else.
Auto-registered
Drop a folder with a template and a pattern.json. Blockstudio registers it and adds it to the inserter automatically.
Fully editable
Unlike pages, patterns are inserted as editable block content. Users can customize each instance independently.
Categorized & searchable
Add categories and keywords in pattern.json. Users find your patterns instantly in the inserter search.
Customizable element mapping
Override which block any HTML element maps to. Point standard tags like <h1>, <p>, and <img> to your own block types.
Remap HTML to custom blocks
By default, standard HTML elements map to core WordPress blocks. Use the element_mapping filter to point any element to a different block type. Every <h1> in your templates will produce your custom block instead of core/heading.
add_filter(
'blockstudio/parser/element_mapping',
function ( $mapping ) {
$mapping['h1'] = 'custom/heading';
$mapping['h2'] = 'custom/heading';
$mapping['p'] = 'custom/paragraph';
$mapping['img'] = 'custom/image';
return $mapping;
}
);Add fields to any block
Extend core blocks, third-party blocks, or your own with custom fields. Pure JSON, no templates, no code.
Custom fields, zero templates
Create a JSON file, target a block with name, and define your fields. The set property maps field values directly to HTML attributes: classes, styles, data attributes, or anything else.
No templates, no render callbacks. Blockstudio handles the output automatically using the WordPress HTML Tag Processor.
{
"name": "core/*",
"blockstudio": {
"extend": true,
"attributes": {
"animation": {
"type": "select",
"label": "Animation",
"options": ["none", "fade", "slide"],
"set": [{
"attribute": "class",
"value": "animate-{attributes.animation}"
}]
}
}
}
}Target any block
Extend a single block, a list of blocks, or use wildcards like core/* to target entire namespaces at once.
The set property
Map field values directly to HTML. Add classes, inline styles, data attributes, or any HTML attribute. No template needed.
Conditional fields
Show and hide fields based on other values. In the example, Duration only appears when Animation is set.
Full feature set
Extensions support all 26 field types, conditional logic, populated data sources, and the same field properties as blocks.
26 different field types at your disposal
Blockstudio provides a versatile array of field types, from basic text fields to complex structures like repeaters and tabs, as well as DOM-focused fields such as classes and data attributes.
Zero-config asset pipeline
SCSS compilation, ES module imports, and automatic minification, all by naming convention. No webpack, no Vite.
Name your files, Blockstudio handles the rest
Drop a style.scss next to your block and it gets compiled, minified, and enqueued automatically. Same for script.js with full ES module support. Import from npm, no bundler needed.
Assets are scoped per block and only loaded when the block is on the page. Use the editor.* prefix for editor-only assets or *.inline.* to inline them directly in the page.
$accent: var(--wp--preset--color--primary);
.hero {
padding: 4rem 2rem;
h1 {
color: $accent;
font-size: clamp(2rem, 5vw, 4rem);
}
&--dark {
background: #0a0a0a;
}
}import gsap from "npm:gsap@3.12.5";
const heading = block.querySelector("h1");
const cards = block.querySelectorAll(".card");
gsap.from(heading, {
opacity: 0,
y: 20,
duration: 0.6,
});
gsap.from(cards, {
opacity: 0, stagger: 0.1,
});SCSS compilation
Write SCSS with nesting, variables, and mixins. Blockstudio compiles and minifies it automatically.
ES module imports
Import npm packages directly in your scripts. Blockstudio downloads and serves them locally. No bundler needed.
Naming convention
style.scss for frontend styles, script.js for frontend scripts, editor.css for editor only. Name the file, done.
Scoped & inlined
Assets load only when the block is on the page. Use *.inline.* to inline scripts and styles directly.
Tailwind v4, compiled in PHP
Write utility classes in your templates. Blockstudio compiles them server-side via TailwindPHP on every request, with automatic file-based caching.
One setting, zero tooling
Set tailwind.enabled to true in your blockstudio.json and start writing utility classes. Blockstudio compiles the CSS server-side, caches it to disk, and injects it as an inline style tag. No Node.js, no CLI, no build step.
Use the blockstudio/tailwind/css filter to define custom themes, utility classes, and variants using Tailwind v4 CSS-first syntax. The classes field type provides autocomplete for all Tailwind utilities in the editor.
add_filter('blockstudio/tailwind/css', function ($css) {
return $css . '
@theme {
--color-brand: #4f46e5;
}
@layer utilities {
.container-narrow {
max-width: 48rem;
margin-inline: auto;
}
}
';
});<section class="bg-brand px-6 py-20">
<div class="container-narrow">
<h2 class="text-4xl font-bold text-white">
<?= $a['heading'] ?>
</h2>
<p class="mt-4 text-lg text-white/80">
<?= $a['description'] ?>
</p>
<a href="<?= $a['url'] ?>"
class="mt-6 inline-block rounded-lg bg-white px-6 py-3 font-semibold text-brand">
<?= $a['buttonText'] ?>
</a>
</div>
</section>Server-side compilation
Every frontend request is compiled via TailwindPHP. No Node.js, no CLI, no build step required.
Automatic caching
Compiled CSS is cached to disk by class names. Same classes, same cache hit, even with dynamic content.
CSS-first config
Tailwind v4 CSS-first configuration. Define custom themes, utilities, and variants directly in your settings.
Live editor preview
A bundled Tailwind CDN script provides instant preview in the block editor. The frontend always uses compiled CSS.
Built for developers
Power features that make complex blocks simple to build and maintain.
Flexible Storage
Store field values in post meta, options, or both at once. Query blocks by meta values, access data via REST API.
Conditional Logic
Show and hide fields based on other field values. 10 comparison operators, nested conditions, and global rules for post type or user role.
50+ PHP & JS Hooks
Filters and actions for every stage: block registration, field rendering, asset loading, and template output. Full control without forking.
JSON Schema
Every configuration file is backed by a JSON Schema. Instant autocomplete, inline docs, and validation in VS Code and JetBrains.
Context API
Share data between parent and child blocks. Define what a parent provides in JSON and access the values in any nested template.
AI Integration
Auto-generated context files describe your entire block library. Works with Cursor, Claude, and other AI coding assistants out of the box.
SEO Integration
Automatic content injection for Yoast, Rank Math, and SEOPress. Field content is extracted and analyzed. No setup required.
Programmatic Rendering
Render any block in PHP with bs_render_block(). Use your blocks as reusable components outside the editor.
Custom Fields
Define reusable field sets as JSON files. Reference them across blocks with the custom field type. Update once, apply everywhere.
Block Transforms
Let users transform one block into another. Add enter and prefix shortcuts so blocks can be inserted by typing.
Dynamic Options
Populate select, radio, and checkbox fields from post queries, taxonomies, user lists, or custom PHP functions.
HTML Utilities
Render field values as data attributes or CSS custom properties directly on the block wrapper. One line in your template.
Dev tools
Built-in tooling for inspecting, debugging, and building with AI.
AI-ready documentation
A static context file with the full documentation and schemas, built for LLM coding assistants.
48k tokens of structured context
Blockstudio ships a pre-built blockstudio-llm.txt file containing the complete documentation and all JSON schemas. The file is assembled at build time, with repeated definitions deduplicated to keep the token count low.
Enable the setting, point your AI tool to the URL, and your coding assistant gets full context about every field type, template pattern, and configuration option in Blockstudio.
# Blockstudio
Context about the Blockstudio WordPress block framework
for LLM coding assistants.
## Documentation
### Getting Started
Create a folder with a block.json and a template file...
### Blocks
Blocks are the fundamental building unit...
### Attributes
Fields are defined in the blockstudio key of block.json...
## Schemas
### Block Schema (blockstudio key from block.json)
```json
{"definitions":{"Attribute":{"anyOf":[...]}},...}
```
### Settings Schema (blockstudio.json)
```json
{"type":"object","properties":{"tailwind":{...},...}}
```Full documentation
All docs pages compiled into a single file, with code examples preserved and formatting stripped.
JSON schemas
Block, settings, page, and extension schemas with deduplication of shared definitions.
Optimized for tokens
~48k tokens. Fits comfortably in modern context windows alongside your own code.
Works everywhere
Cursor, Claude Code, GitHub Copilot, or any LLM tool that accepts a URL or text file.
Questions & Answers
Everything you need to know about Blockstudio. Can't find what you're looking for? Reach out to our support team.
The official extension kit
Premium site templates, AI system instructions, and a private Discord community. One-time purchase, lifetime updates.
- 150+ site templates
- AI system instructions
- Lifetime updates
- Private Discord community