Guides

Building blocks

Blocks are reusable content components. You define a schema in Admin, editors fill fields on entries, and your frontend maps each block type to a React component. This guide walks through the starter Image block end to end.

What is a block?

In Blocklify, a block is a component with:

  • A machine type (e.g. image, hero) — this is the key your theme uses in blockMap.
  • A JSON schema listing fields editors can fill.
  • Flags: root (content type / page-level) vs nestable (can sit inside a blocks field on a page).

Starter spaces already include nestable Hero, Text, and Image blocks plus a Page root type. Clean spaces start empty — you add blocks under Admin → Blocks.

Field types

Each schema field has a name, type, and optional required / display metadata. Supported types:

TypeUse for
textShort strings (titles, alt text)
textareaLonger plain text
wysiwygRich text / HTML
numberNumeric values
booleanToggles
datetimeDates and times
assetImages and files from the asset library (stored as asset ID)
linkURLs / CTA targets
single_option / multiple_optionsEnums / multi-select
groupOne level of nested fields, such as a button label and link
blocksNested block lists (e.g. page body)

There is no separate image field type — images use type: "asset". The starter block whose type is image is a component that happens to contain an asset field also named image.

Group fields

A group holds normal fields one level deep. Use it for a button: a text label and a link. Groups cannot contain another group or a blocks list. Entry content stores the group as an object.

{
  "name": "button",
  "type": "group",
  "displayName": "Button",
  "fields": [
    { "name": "label", "type": "text", "displayName": "Button label" },
    { "name": "link", "type": "link", "displayName": "Link" }
  ]
}
{
  "button": {
    "label": "Get started",
    "link": { "kind": "url", "url": "https://example.com" }
  }
}

Example: Image block

The starter Image block is nestable and matches this schema (same shape Starter spaces seed automatically):

{
  "type": "image",
  "fields": [
    { "name": "image", "type": "asset", "required": true },
    { "name": "caption", "type": "text" },
    { "name": "alt", "type": "text" }
  ]
}
  • image — required asset picker (photo / file).
  • caption — optional figcaption text.
  • alt — accessibility text for the <img>.

Create it in Admin

If you are on a clean space (or want a custom variant):

  1. Open Admin → Blocks and create a block.
  2. Set the type to image (machine name — keep it stable; themes key off it).
  3. Mark it nestable so it can sit in a page body blocks field.
  4. Add the three fields above: asset image, text caption, text alt.
  5. On your page content type / root block, allow image in the blocks field’s allowed list.

Upload media under Admin → Assets, then pick it from the asset field when editing an entry.

Entry content shape

Inside a page body (or any blocks field), an Image block instance looks like:

{
  "type": "image",
  "_uid": "clx…",
  "image": "classet…",
  "caption": "Sunset over the harbor",
  "alt": "Orange sky reflected in calm water"
}

The image field stores the asset ID (string), not a full URL object. Empty pickers are often "" until an editor selects a file.

Resolve asset fields

The Content API and live-preview draft payload leave asset fields as IDs. Your theme (or a small helper) should resolve them when you need url, alt, and mime metadata:

GET /api/spaces/{spaceId}/assets/{assetId}
Authorization: Bearer blocklify_…

A successful response includes fields such as id, url, filename, mimeType, and asset-level alt / title. Map the ID to something your component can render:

// After resolving the asset ID:
const image = assetId
  ? { url: asset.url, alt: asset.alt ?? undefined }
  : undefined;

Prefer the block’s own alt field for the <img> when present; fall back to the asset’s alt or the caption.

Full OpenAPI details: API reference.

Theme component

Once image is an object with url (or you accept a pre-expanded shape), a minimal React component looks like this:

type ImageBlockProps = {
  image?: { url?: string };
  caption?: string;
  alt?: string;
  BlocklifyEditable?: Record<string, unknown>;
};

export function ImageBlock({
  image,
  caption,
  alt,
  BlocklifyEditable = {},
}: ImageBlockProps) {
  if (!image?.url) return null;

  return (
    <figure className="px-6 py-6" {...BlocklifyEditable}>
      <img
        src={image.url}
        alt={alt ?? caption ?? ""}
        className="mx-auto max-w-2xl w-full rounded-lg object-cover"
      />
      {caption ? (
        <figcaption className="mt-2 text-center text-sm opacity-70">
          {caption}
        </figcaption>
      ) : null}
    </figure>
  );
}

The built-in demo at /preview uses the same pattern (plus a shared Image UI helper with placeholders).

Register in blockMap

Pass the component into BlocklifyPreview (or your published renderer) under the block’s machine type. Optional aliases help if older content used a longer name:

import type { BlockMap } from "@blocklify/preview";
import { ImageBlock } from "./blocks/image-block";

export const blockMap: BlockMap = {
  image: ({ block, BlocklifyEditable }) => (
    <ImageBlock
      image={block.image as { url?: string }}
      caption={block.caption as string}
      alt={block.alt as string}
      BlocklifyEditable={BlocklifyEditable}
    />
  ),
  // Optional alias if some entries use image_block
  image_block: ({ block, BlocklifyEditable }) => (
    <ImageBlock
      image={block.image as { url?: string }}
      caption={block.caption as string}
      alt={block.alt as string}
      BlocklifyEditable={BlocklifyEditable}
    />
  ),
};

If block.image is still a string ID at render time, resolve it before this point (loader, client helper, or wrapper component).

Live edit

Spreading BlocklifyEditable onto the root figure lets editors click the block in the live preview iframe to focus it in the entry editor. For field-level focus, see Enable live edit on theme blocks.

Next steps