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 inblockMap. - 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:
| Type | Use for |
|---|---|
text | Short strings (titles, alt text) |
textarea | Longer plain text |
wysiwyg | Rich text / HTML |
number | Numeric values |
boolean | Toggles |
datetime | Dates and times |
asset | Images and files from the asset library (stored as asset ID) |
link | URLs / CTA targets |
single_option / multiple_options | Enums / multi-select |
group | One level of nested fields, such as a button label and link |
blocks | Nested 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):
- Open Admin → Blocks and create a block.
- Set the type to
image(machine name — keep it stable; themes key off it). - Mark it nestable so it can sit in a page
bodyblocks field. - Add the three fields above: asset
image, textcaption, textalt. - On your page content type / root block, allow
imagein 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
- Getting started — space, entry, and read token.
- Next.js theme blocks or React (Vite) theme blocks — wire
blockMapin a clean app. - API reference — components, entries, and assets endpoints.