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

[Field types reference](https://blockstudio.dev/docs/blocks/attributes/field-types/)

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.

[Explore components](https://blockstudio.dev/docs/blocks/react-components/)

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.

[Template languages](https://blockstudio.dev/docs/blocks/templating/blade/)

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

[Conditional logic](https://blockstudio.dev/docs/blocks/attributes/conditional-logic/)

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

[Repeater patterns](https://blockstudio.dev/guides/field-patterns/#repeater-patterns)

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.

[Custom fields](https://blockstudio.dev/docs/blocks/attributes/custom-fields/)

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.

[Asset processing](https://blockstudio.dev/docs/blocks/assets/)

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.

[Read the guide](https://blockstudio.dev/guides/block-tags/)

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

[Get Plus](https://blockstudio.dev/plus/)
