Skip to content
NewBlockstudio 7.7

The block framework
for WordPress

Custom blocks from plain files. Define fields in JSON, write templates in PHP, Twig, or Blade. No build step required.

Terminal
composer require blockstudio/blockstudio
Get Started
Download v7.7.13 (opens in a new tab)

Blocks

Create custom blocks with JSON and PHP, Twig, or Blade templates. 27 field types, no build step.

Pages

Write full WordPress pages as template files and sync them into native blocks with one command.

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

27 built-in types including repeaters, color pickers, code editors, and media, plus field types you register.

Asset Processing

SCSS compilation, ES modules, scoped styles, and optional 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.

Get started
block.json
{
  "name": "starter/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text" },
      { "id": "showCta", "type": "toggle" },
      { "id": "background", "type": "color" }
    ]
  }
}
index.php
<section useBlockProps class="hero"
  style="background: <?= esc_attr($a['background']['value'] ?? '') ?>">
  <h1><?= esc_html($a['heading']) ?></h1>

  <?php if ($a['showCta']): ?>
    <a href="/contact">Get Started</a>
  <?php endif; ?>

  <InnerBlocks />
</section>
style.scss
.hero {
  padding: 4rem 2rem;

  h1 {
    font-size: 3rem;
    font-weight: 700;
  }

  a {
    padding: 0.75rem 1.5rem;
    color: #fff;
    background: #18181b;
  }
}

React features, PHP templates

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 /> handles nested child blocks, while useBlockProps marks the block wrapper.

Blockstudio handles the editor integration automatically. In the editor, these become real React components. On the frontend, they render as plain server-side HTML.

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 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 such as $isEditor to tailor output per environment.

Use <InnerBlocks />, <RichText />, and <MediaPlaceholder /> directly in templates without writing JavaScript.

PHP
<section class="hero">
  <h1><?= esc_html($a['heading']) ?></h1>
  <p><?= esc_html($a['description']) ?></p>
  <?php if ($a['showCta']): ?>
    <a href="<?= esc_url($a['ctaUrl']) ?>">
      <?= esc_html($a['ctaLabel']) ?>
    </a>
  <?php endif; ?>
  <InnerBlocks />
</section>

Full pages, defined in code

Create complete WordPress pages from template files. HTML maps to core blocks, and one command syncs them into the editor.

Write HTML, get blocks

Standard elements such as <h1>, <p>, and <ul> map to core blocks automatically. Use <block> for everything else.

Define complete layouts in your codebase. When you run wp bs pages sync, Blockstudio parses the templates into real WordPress pages with real blocks, fully editable in the block editor.

index.php
<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="core/group" layout='{"type":"grid"}'>
      <h2>Our Stack</h2>
    </block>
  </block>
</block>

Explicit sync

Run wp bs pages sync to apply template changes. Unchanged pages cost zero writes.

Template locking

Lock structure while clients edit content. Ideal for landing pages and marketing sites.

Keyed blocks

Assign keys so user edits persist across template updates. Sync structure, keep content.

Version controlled

Pages live in files. Track changes in Git, deploy environments, and review them 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 pattern.json and a template file. Blockstudio registers the pattern automatically, with no register_block_pattern() boilerplate.

Patterns are inserted as real, editable blocks. Users get a starting layout they can customize while you maintain templates in version control.

index.php
<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>
    <block name="core/column">
      <h3>Pro</h3>
      <ul><li>Priority support</li><li>Custom integrations</li></ul>
    </block>
  </block>
</div>

Same syntax as pages

Standard HTML maps to core blocks; the block tag handles everything else.

Auto-registered

Drop in a template and pattern.json. Blockstudio registers it automatically.

Fully editable

Patterns are inserted as editable block content and customized per instance.

Categorized and searchable

Categories and keywords make patterns easy to find in the inserter.

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 maps to core WordPress blocks. Use the element_mapping filter to point any element at another block type. Every <h1> can produce your custom block instead of core/heading.

functions.php
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 fields. The set property maps field values directly to classes, styles, data attributes, or anything else.

No templates and no render callbacks. Blockstudio handles output automatically using the WordPress HTML Tag Processor.

extend-animation.json
{
  "name": "core/*",
  "blockstudio": {
    "extend": { "priority": 10 },
    "attributes": [
      {
        "id": "animation",
        "type": "select",
        "allowNull": "None",
        "options": [
          { "value": "fade", "label": "Fade" },
          { "value": "slide", "label": "Slide" }
        ],
        "set": [{
          "attribute": "class",
          "value": "animate-{attributes.animation}"
        }]
      }
    ]
  }
}

Target any block

Extend one block, a list, or an entire namespace with wildcards such as core/*.

The set property

Map field values directly to classes, styles, data attributes, or any HTML attribute.

Conditional fields

Show and hide fields based on other values with the same operators blocks use.

Full feature set

All field types, conditional logic, populated sources, and reusable properties.

27 field types at your disposal

From basic text fields to repeaters and tabs, plus DOM-focused fields such as classes and data attributes. Register your own types on top.

Explore field types
attributesblockcheckboxclassescodecolordatedatetimefilesgradientgrouphtml-tagiconlinkmessagenumberradiorangeselecttabstexttextareatogglerepeaterrichtextunitwysiwyg

Zero-config asset pipeline

SCSS compilation, ES module imports, and optional minification, all by naming convention. No webpack, no Vite.

Name your files, Blockstudio handles the rest

Drop style.scss next to a block and it gets compiled and enqueued automatically. The same is true for script.js, with ES module support and direct npm imports. Minification is one setting away.

Assets are scoped per block and loaded only when needed. Use editor.* for editor-only assets or *.inline.* to inline them in the page.

SCSS
$accent: var(--wp--preset--color--primary);

.hero {
  padding: 4rem 2rem;
  h1 { color: $accent; font-size: clamp(2rem, 5vw, 4rem); }
  &--dark { background: #0a0a0a; }
}

SCSS compilation

Write nesting, variables, and mixins. Blockstudio compiles it for you.

ES module imports

Import npm packages directly. Blockstudio downloads and serves them locally.

Naming convention

style.scss, script.js, editor.css. Name the file and you are done.

Scoped and inlined

Assets load only when the block is present; inline them with the filename convention.

Tailwind v4, compiled in PHP

Write utility classes in templates. Blockstudio compiles them server-side via TailwindPHP with automatic file caching.

One setting, zero tooling

Set tailwind.enabled to true in blockstudio.json and write utility classes. Blockstudio compiles CSS server-side, caches it, and injects it without Node.js.

Use blockstudio/tailwind/css to define themes, utilities, and variants with Tailwind v4 CSS-first syntax. The classes field provides editor autocomplete.

functions.php
add_filter('blockstudio/tailwind/css', function ($css) {
  return $css . '
    @theme { --color-accent: #4f46e5; }
    @utility container-narrow {
      max-width: 48rem;
      margin-inline: auto;
    }
  ';
});

Server-side compilation

TailwindPHP compiles the classes each page uses. No Node or build step.

Automatic caching

Compiled CSS is cached to disk by class set for fast repeat requests.

CSS-first config

Define themes, utilities, and variants directly with Tailwind v4 CSS.

Live editor preview

Instant editor preview while the frontend uses server-compiled CSS.

Components included

59 UI components ship with Blockstudio, ready to compose in your templates.

Interactive parts as block tags

Turn on ui.enabled and Blockstudio registers 59 headless components under the bsui namespace: dialogs, menus, tabs, comboboxes, date and file inputs, toasts, and more, driven by the WordPress Interactivity API.

Write them as block tags in any template, page, or pattern, render them from PHP, or allow bsui/* under blockTags to use them in post content. Each one is a regular block with its own block.json that works in the editor canvas as well as on the page, and a page loads the CSS and JS of only the components it renders.

Give a form control a name and it renders a hidden input, so a surrounding form posts plain values without JavaScript of your own. Selects, menus, and dialogs use the real ARIA patterns, with arrow keys, type-ahead, and focus that stays inside an open modal.

Styling runs on --bs-ui-* tokens with a complete dark scheme behind a .dark class, all inside the bsui cascade layer, so plain theme CSS wins without important flags or specificity games. Add your own variant to a component through a filter, and read the bundled app/* demo apps to see the components composed into larger interfaces.

index.php
<bs:bsui-dialog>
  <bs:bsui-dialog-trigger trigger_label="Edit profile" trigger_variant="outline" />
  <bs:bsui-dialog-backdrop />
  <bs:bsui-dialog-popup>
    <bs:bsui-dialog-header>
      <bs:bsui-dialog-title content="Edit profile" />
      <bs:bsui-dialog-description content="Make changes to your profile here, then save when you are done." />
    </bs:bsui-dialog-header>
    <bs:bsui-dialog-content>
      <bs:bsui-field>
        <bs:bsui-field-label text="Name" />
        <bs:bsui-input defaultValue="Pedro Duarte" />
      </bs:bsui-field>
    </bs:bsui-dialog-content>
    <bs:bsui-dialog-footer>
      <bs:bsui-dialog-close label="Cancel" variant="outline" />
      <bs:bsui-dialog-close label="Save changes" variant="default" />
    </bs:bsui-dialog-footer>
  </bs:bsui-dialog-popup>
</bs:bsui-dialog>

Built for developers

Power features that make complex blocks simple to build and maintain.

Flexible Storage

Store values in post meta, options, or both. Query blocks by meta and expose data through REST.

Conditional Logic

Show fields based on values with comparison operators, nested conditions, and global rules.

Over 130 PHP & JS Hooks

Filters and actions for registration, fields, assets, settings, and output.

JSON Schema

Autocomplete, inline docs, and validation in VS Code and JetBrains.

Context API

Share declared data between parent and nested child blocks.

AI Integration

A documentation index for coding agents and a generated AGENTS.md for your project.

SEO Integration

Automatic content injection for Yoast, Rank Math, and SEOPress.

Programmatic Rendering

Render blocks from PHP and use them as components outside the editor.

Custom Fields

Define reusable field sets once and reference them across blocks.

Block Transforms

Transform blocks and add enter or prefix insertion shortcuts.

Dynamic Options

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

HTML Utilities

Render data attributes or CSS variables on the block wrapper.

Plugin, MU Plugin, or Composer

Install the plugin zip, load it as a must-use plugin, or require it with Composer inside a theme or plugin. Bedrock can include it early, and BLOCKSTUDIO_URL covers custom package URLs.

Updates Without Clashes

Bundled libraries such as TailwindPHP, ScssPhp, and Minify are namespaced private copies, so they never replace another plugin’s versions. Zip installs update from GitHub releases, with an optional access token.

Upgrading from v6 to v7

Blocks written for v6 keep working: the old blockstudio/ import prefix, camelCase hook names, and dash asset suffixes are still supported. The migration guide covers what changed.

Dev tools

Built-in tooling for inspecting, debugging, and building with AI.

Canvas

A Figma-like overview of all your managed pages. Pan, zoom, and inspect your site in a single view.

admin.php?page=blockstudio-canvas

Element Grabber

Hold Cmd+C on any element to copy its markup and block template path. Paste that context into your AI editor.

?blockstudio-devtools

Built for agents

Documentation an agent can index, a contract for your project, and analysis that rejects what does not fit.

An index, a contract, and a gate

Blockstudio ships blockstudio-llm.txt, an index of every document with its route, purpose, and the identifiers it owns, plus blockstudio-llm-full.txt with the full text. An agent reads the index, then opens only the page it needs.

In your project, blockstudio-agents writes an AGENTS.md from your own files and settings, and blockstudio-phpstan runs the preset you choose, from a managed commit hook if you want one.

blockstudio-llm.txt
## Docs / Blocks / Attributes

### Registering Attributes
route: /docs/blocks/attributes/registering
file: docs/docs/blocks/attributes/registering.md
purpose: Learn how to register custom attributes for your blocks.
php: $a

### Field Types
route: /docs/blocks/attributes/field-types
file: docs/docs/blocks/attributes/field-types.md
purpose: All available field types and their properties in Blockstudio.
hooks: blockstudio/field_types

An index first

Every document with its route, purpose, and identifiers, in about 11k tokens.

Full text on demand

All documentation and JSON schemas in one file, about 164k tokens.

A generated AGENTS.md

blockstudio-agents describes what your project authors, enables, and rejects.

Analysis presets

base, theme, and extreme-theme hold templates to block.json and more.

Full-stack blocks

Build complete applications inside a block folder. Database, server logic, scheduled tasks, and CLI, all from files.

Drop a file, get an API

Add db.php to define a data model. Blockstudio creates REST endpoints, validates input, manages storage, and provides JavaScript and PHP APIs.

Add rpc.php for server functions and cron.php for scheduled tasks. Each file does one thing, without controllers or build tooling.

db.php
<?php
return [
  'storage'    => 'sqlite',
  'userScoped' => true,
  'capability' => [
    'create' => true,
    'read'   => true,
    'update' => true,
    'delete' => true,
  ],
  'fields' => [
    'text' => ['type' => 'string', 'required' => true],
    'done' => ['type' => 'boolean', 'default' => false],
  ],
];

Server functions in one line

Define PHP functions in rpc.php and call them with bs.fn(). Blockstudio handles routing, authentication, CSRF protection, and JSON serialization.

rpc.php
<?php
use Blockstudio\Db;

return [
  'toggle' => function (array $params): array {
    $db   = Db::get('my-theme/todo');
    $id   = (int) ($params['id'] ?? 0);
    $todo = $db->get_record($id);
    if ($todo) {
      $db->update($id, ['done' => !$todo['done']]);
    }
    return ['success' => (bool) $todo];
  },
];

Database

Schema-defined CRUD in 6 storage modes: table, sqlite, jsonc, storh, meta, post_type.

RPC

Server functions callable from the frontend with bs.fn().

Cron

Scheduled tasks in cron.php, registered with WP-Cron.

CLI

Manage blocks, pages, records, RPC, cron jobs, and settings with wp bs.

CSRF Protection

Public endpoints are protected automatically with an explicit open mode.

User Scoping

Automatically isolate data per user with no manual ownership filters.

Portability

With SQLite or JSONC, code and data travel together as one folder.

Components

Programmatic UI components use the complete Blockstudio pipeline.

Static when it can be

Turn on static prerendering and anonymous visitors get stored HTML, while everything personal stays live.

Static prerendering

Off until you say so

performance.staticPrerender in blockstudio.json turns it on.

Before WordPress boots

With earlyServe on, a drop-in sends stored pages before WordPress loads.

Fresh on save

Saving a post purges or re-renders its stored page and the front page.

Live where it must be

Logged-in requests, search, and dynamicPaths render live by default.

Questions & Answers

Everything you need to know about Blockstudio. Missing an answer? Ask on GitHub.

Open an issue

What is Blockstudio?

A WordPress plugin that lets you build custom blocks with JSON and a template file. Define fields and write markup without React tooling.

Do I need to know JavaScript?

No. If you can write HTML and basic PHP, you can build blocks. Blockstudio handles editor internals.

Does it work with my theme?

Yes. Blocks use the native WordPress block API and work with any block-compatible theme.

How is this different from ACF blocks?

ACF PRO also registers blocks through block.json and renders PHP templates with InnerBlocks, and since ACF PRO 6.8.1 it can declare a block’s fields there too. Blockstudio discovers block folders without a register_block_type() call, renders PHP, Twig, or Blade, compiles each block’s styles and scripts, adds RichText in templates, file-based pages, patterns, and extensions, and is free under the GPL rather than part of a paid licence.

What template languages are supported?

PHP out of the box, Twig once timber/timber is installed, and Blade through illuminate/view 8 to 12 and a short render filter that calls Blockstudio\Blade_Renderer. All three get the same variables and components, and Blade can also render pages, patterns, and Site Editor templates.

Can I extend existing blocks?

Yes. Extensions add fields to core, third-party, or custom blocks, including whole namespaces through wildcards.

How does the asset pipeline work?

Use naming conventions such as style.scss, script.js, and editor.css. Blockstudio compiles, scopes, and enqueues them, and minifies them when you turn minification on.

Is there IDE support?

Yes. JSON Schema provides autocomplete, inline documentation, and validation in compatible editors.

What are the requirements?

WordPress 6.7 or later and PHP 8.2 or later.

Is Blockstudio free?

Yes. Blockstudio is free and open source, with extensions, all field types, assets, pages, and patterns included.

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
Get Plus