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.

Terminal

composer require blockstudio/blockstudio

Get Started

Download v7.6.14

Blocks

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.

Get started

1block.json

block.json

{
  "name": "starter/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": {
      "heading": { "type": "text" },
      "showCta": { "type": "toggle" },
      "background": { "type": "color" }
    }
  }
}

2index.php

index.php

<section style="background: <?= $a['background'] ?>">
  <h1><?= $a['heading'] ?></h1>

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

  <InnerBlocks />
</section>

3style.scss

style.scss

section {
  padding: 4rem 2rem;

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

  a {
    padding: .75rem 1.5rem;
    background: currentColor;
  }
}

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="true" 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.

Explore components

index.php

<div useblockprops="true" 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 such as $isEditor to tailor output per environment.

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

Learn more about templating

PHP

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

Twig

<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 %}
  <InnerBlocks />
</section>

Blade

<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
  <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 such as <h1>, <p>, and <ul> map to core blocks automatically. Use <block> for everything else.

Define complete layouts in your codebase. Blockstudio parses the templates and creates real WordPress pages with real blocks, fully editable in the block editor.

Learn more about pages

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="grid">
      <h2>Our Stack</h2>
    </block>
  </block>
</block>

Automatic sync

Pages sync to WordPress on every admin load. Change your template and the editor updates.

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.

Learn more about patterns

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.

Learn more about element mapping

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.

Learn more about extensions

extend-animation.json

{
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "attributes": {
      "animation": {
        "type": "select",
        "options": ["none", "fade", "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.

26 different field types at your disposal

From basic text fields to repeaters and tabs, plus DOM-focused fields such as classes and data attributes.

Explore field types

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 style.scss next to a block and it gets compiled, minified, and enqueued automatically. The same is true for script.js, with ES module support and direct npm imports.

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

Learn more about assets

SCSS

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

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

ES Modules

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 nesting, variables, and mixins. Blockstudio compiles and minifies it automatically.

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.

Learn more about Tailwind

functions.php

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

Template

<section class="bg-accent 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>
  </div>
</section>

Server-side compilation

Every frontend request is compiled through TailwindPHP. 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.

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.

50+ PHP & JS Hooks

Filters and actions for registration, fields, assets, 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

Generated context describes the block library for coding agents.

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.

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.

?blockstudio-canvas

Element Grabber

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

?blockstudio-devtools

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 containing the complete documentation and JSON schemas, with repeated definitions deduplicated.

Enable the setting, point your AI tool at the URL, and it gets full context about every field type, template pattern, and configuration option.

AI integration docs

blockstudio-llm.txt

# 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...

## Schemas

### Block Schema
```json
{"definitions":{"Attribute":{"anyOf":[...]}},...}
```

Full documentation

All documentation in one context file with code examples preserved.

JSON schemas

Block, settings, page, and extension schemas with shared definitions deduplicated.

Optimized for tokens

About 48k tokens, leaving room for your own code in modern context windows.

Works everywhere

Claude Code, Codex, Cursor, Copilot, or any tool accepting a URL or file.

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.

Full-Stack Blocks guide

db.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

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

Database

Schema-defined CRUD across MySQL, SQLite, JSONC, or post meta.

RPC

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

Cron

Scheduled tasks in cron.php with automatic cleanup.

CLI

Manage blocks, 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.

Questions & Answers

Everything you need to know about Blockstudio. Can’t find what you’re looking for? Reach out to our support team.

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?

Everything is file-based, with no admin registration UI or PHP boilerplate, plus SCSS, ES modules, scoped assets, and InnerBlocks.

What template languages are supported?

PHP, Twig through Timber, and Blade through Sage or Acorn. All share the same variables and components.

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 minifies automatically.

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.

450+ site templates
AI system instructions
Lifetime updates
Private Discord community

Get Plus

The block frameworkfor WordPress

Blocks

Pages

Patterns

Extensions

Field Types

Asset Processing

JSON Schema

Templating

Custom blocks in 3 files

React features, PHP templates

All inside the same file

Write templates in PHP, Twig, or Blade

Same variables, any language

Full pages, defined in code

Write HTML, get blocks

Automatic sync

Template locking

Keyed blocks

Version controlled

Reusable patterns from template files

Template files, not registration code

Same syntax as pages

Auto-registered

Fully editable

Categorized and searchable

Customizable element mapping

Remap HTML to custom blocks

Add fields to any block

Custom fields, zero templates

Target any block

The set property

Conditional fields

Full feature set

26 different field types at your disposal

Zero-config asset pipeline

Name your files, Blockstudio handles the rest

SCSS compilation

ES module imports

Naming convention

Scoped and inlined

Tailwind v4, compiled in PHP

One setting, zero tooling

Server-side compilation

Automatic caching

CSS-first config

Live editor preview

Built for developers

Flexible Storage

Conditional Logic

50+ PHP & JS Hooks

JSON Schema

Context API

AI Integration

SEO Integration

Programmatic Rendering

Custom Fields

Block Transforms

Dynamic Options

HTML Utilities

Dev tools

Canvas

Element Grabber

AI-ready documentation

48k tokens of structured context

Full documentation

JSON schemas

Optimized for tokens

Works everywhere

Full-stack blocks

Drop a file, get an API

Server functions in one line

Database

RPC

Cron

CLI

CSRF Protection

User Scoping

Portability

Components

The block framework
for WordPress