Skip to content

Page Builder

The Page Builder is the console’s visual editor for pages. Editors drag blocks onto a canvas, edit each block’s properties, and style it per device. The canvas is your own site, rendered inside the console, so editors see exactly what visitors will see. A page is an ordinary content entry: its layout is stored in a blocks field as JSON, and your site reads it from the Content API and renders it with @plenary/react.

Use the Page Builder for marketing pages, landing pages, and anything editors need to lay out themselves. Use plain fields for structured content such as blog posts and products.

Term Meaning
Page Any content entry whose model has a field of type blocks. There is no special page model kind; a collection or singleton with a blocks field is enough.
Document The value of a blocks field: { "version": 1, "root": [ ...nodes ] }.
Block (node) One element in the document: a component key, its props, and optionally child slots.
Component The React component your site renders for a block. Five are built in (box, section, text, image, video); you register your own.
Slot A named region inside a block that holds other blocks.
Bridge PlenaryBridge, the SDK component on your site that lets the console drive the canvas. See Live Preview.
Manifest The list of components (and design tokens) your site registers, which the console uses for its palette and property forms.

The console never renders your components itself. It frames your site’s preview URL, and your site renders every block. That is why custom components must be registered in your site’s code, not in the console.

  1. Go to Content Management → Content and open a model, or create one with New model.
  2. On the Fields tab, click Add field and choose the type Blocks (“A Page Builder region edited on the canvas”). Give it a key such as body.
  3. On the Settings tab, in Metadata, turn on Show preview.
  4. Enter a Preview URL: a template that resolves to the page on your site that mounts the bridge, such as https://www.example.com/preview/{{slug}}. See Live Preview.
  5. Optionally turn on Open entries in Page Builder so entries open on the canvas instead of the form editor.
  6. Click Save model.

A model with a blocks field can always open the Page Builder. Without a preview URL the canvas shows “This model has no preview URL. Add one in the model editor to see this entry on your site.” If a model has more than one blocks field, only the first is editable in the Page Builder.

You can also define the model in YAML. See Models as Code and the blocks type in Field Types.

  • With Open entries in Page Builder on, entries open directly in the Page Builder.
  • Otherwise, the form editor shows each blocks field as an Edited in the Page Builder card with an Open builder button, and an Open Preview button when the model has a preview URL.
  • In the Page Builder, Open in editor switches to the form editor, and Return to {Pages} goes back to the entry list.

A new entry must be saved once before the canvas can load, because the preview URL is built from the saved entry (“Save this entry to preview it.”).

Area What it holds
Left panel, Blocks tab Tree: the page’s blocks as an outline. Palette: every available block, grouped by category, with Search blocks….
Left panel, Data tab The entry’s other fields, such as title and SEO fields.
Center The artboard: your site, live. A status chip reads Preview connected or Waiting for preview.
Toolbar Viewport switcher (Desktop 1280, Tablet 834, Mobile 390), Zoom (with Fit), Refresh preview, Open in new tab, Undo, Redo, History, Save Changes.
Right panel Properties (the selected block’s props) and Style (its per-device styles).

The artboard lays your page out at the exact device width and scales it to fit, so media queries behave as on a real device. Zoom from 10% to 200% with the zoom menu or Ctrl/Cmd + scroll wheel. Pan with the middle mouse button.

  • Drag a block from the Palette onto the canvas or into the Tree. A line shows where it will land; a dashed box shows an empty Section column.
  • Click a block on the canvas or in the tree to select it. The tree expands to the selection.
  • Drag tree rows to reorder or nest blocks. A block cannot be dropped inside itself.
  • Use the row actions for Rename, Duplicate, and Delete. A renamed block keeps its name only in the tree.
  • A Section shows its columns as Column N rows. Use Add column and Remove column (or change Columns in Properties). Removing columns deletes their content, so the console asks first (“Remove columns?”).

The Properties tab shows one input per prop the component declares, using the same inputs as content fields. Props are per block and the same on every device; per-device differences belong on the Style tab.

Double-click a plain-text Text block on the canvas to edit it in place. Enter commits, Shift+Enter inserts a line break, and Escape cancels. Rich text is edited in the Properties panel.

These work in the console and while focus is inside the canvas. They are ignored while you type in an input.

Shortcut Action
Ctrl/Cmd + Z Undo
Ctrl/Cmd + Shift + Z, or Ctrl/Cmd + Y Redo
Ctrl/Cmd + S Save
Ctrl/Cmd + D Duplicate the selected block
Ctrl/Cmd + C / X / V Copy, cut, or paste blocks
Ctrl/Cmd + Shift + V Paste, replacing the selected block
Delete or Backspace Delete the selected block

Undo history holds the last 100 changes; rapid typing in one input counts as one change. History is cleared when you open another entry. Copied blocks stay inside the Page Builder (not the system clipboard), and each paste gets new block ids. A paste goes into the selected block when it has exactly one slot, otherwise after it. Section columns cannot be deleted, duplicated, cut, or replaced by a paste.

Edits are a draft until you click Save Changes, and the saved entry follows the model’s normal publishing rules. See Entries and Publishing. The canvas always shows the unsaved draft.

Your site receives the document as the blocks field’s value in the Content API:

{
"version": 1,
"root": [
{
"id": "3f0c2b9e-6a51-4d0e-9a57-1f4f0f3a2c11",
"component": "hero",
"label": "Top banner",
"props": {
"heading": "Ship pages faster",
"showButton": true,
"buttonLabel": "Get started",
"style": { "color": "var(--ink)" },
"styleMobile": { "paddingTop": "32px" }
}
},
{
"id": "8d2e4c1a-0b7f-4e44-8f61-2b9f3c5d7e80",
"component": "section",
"props": { "columns": 2, "gap": 16 },
"slots": {
"0": [
{
"id": "a1",
"component": "box",
"props": { "style": { "display": "flex", "flexDirection": "column" } },
"slots": {
"children": [{ "id": "a2", "component": "text", "props": { "content": "Left column", "as": "h3" } }]
}
}
],
"1": [
{
"id": "b1",
"component": "box",
"props": {},
"slots": {
"children": [
{
"id": "b2",
"component": "image",
"props": { "media": { "media_id": "556a8e94-3c04-4659-85e3-cea0f9f07ae2" }, "alt": "Team photo", "width": 600 }
}
]
}
}
]
}
}
]
}
Key Description
version Always 1.
root Top-level nodes, in order.
id A unique id the console assigns. Stable across reorders.
component The registered component key.
label Optional tree name an editor gave the block. Not passed to your component.
props The block’s prop values as plain JSON. style, styleTablet, and styleMobile are reserved for editor styles.
slots Child nodes by slot name. children is the default slot; a Section keys its columns "0", "1", and so on. Each Section column holds exactly one Box.

The TypeScript types are PlenaryDocument and PlenaryNode from @plenary/core.

The server checks the document’s shape on every entry write: an object with a numeric version and an array root; each node with a non-empty string id and component, an object props, and, if present, an object slots of node arrays. A failure returns entry_dom_invalid with a reason such as root[0].props must be an object. The server does not check component keys or prop values, because it does not know your components. A key your site has not registered renders as an “Unknown component” placeholder.

You can write documents through the Content API yourself, for example to generate pages. Give each node a unique id.

Fetch the entry with @plenary/client and pass the document to PlenaryPage:

app/[slug]/page.tsx
import { notFound } from "next/navigation";
import { createClient, PlenaryNotFoundError } from "@plenary/client";
import type { PlenaryDocument } from "@plenary/core";
import { PlenaryPage } from "@plenary/react";
import "@/lib/blocks";
const plenary = createClient({
baseUrl: process.env.PLENARY_BASE_URL!,
siteKey: process.env.PLENARY_SITE_KEY!,
apiKey: process.env.PLENARY_API_KEY!,
locale: process.env.PLENARY_LOCALE!,
});
export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
const { slug } = await params;
try {
const entry = await plenary.getEntry<{ body?: PlenaryDocument }>("page", slug);
return entry.data.body ? <PlenaryPage document={entry.data.body} client={plenary} /> : null;
} catch (err) {
if (err instanceof PlenaryNotFoundError) notFound();
throw err;
}
}

PLENARY_BASE_URL is your instance’s origin (for example https://your-instance.plenarycms.io), and PLENARY_API_KEY is a public API key for the site. Pass client so image and video blocks can resolve their media. The Page Builder Site example is a complete, working site.

The example sets force-dynamic, so every request fetches the page from Plenary. To serve cached pages instead (incremental static regeneration, for example on Vercel), give the route a revalidate time and a generateStaticParams that returns an empty array, then add the revalidation webhook so an edit refreshes the page straight away:

app/[slug]/page.tsx
export const revalidate = 3600;
export async function generateStaticParams() {
return [];
}

The empty generateStaticParams matters. Without it, Next.js renders a dynamic route such as [slug] or a catch-all on every request, and neither revalidate nor tagged fetches have any effect. With it, each page is rendered on its first visit and cached until the time runs out or the webhook revalidates it.

Five blocks are always available. There are no separate heading, button, spacer, or columns blocks: a heading is a Text block with Render as set to a heading, and columns are a Section.

Key Palette name Props Slots Style panels
box Box className children layout, size, background, css
section Section columns (1 to 6, default 1), gap (px, default 16), className one per column, "0" to "5" size, background, css
text Text content (rich text), as (p, h1 to h6, span, code; default p) none size, typography, css
image Image media, alt, width, height, quality, crop none size, css
video Video media (video file), poster, controls, autoplay, loop, muted, playsinline, preload none size, css
  • Box is the general-purpose container. New boxes start as a flex column.
  • Section lays out equal columns. Each column holds one permanent Box, shown in the tree as Column N; style the column by styling that Box.
  • Text renders plain text in the element chosen by as. Rich text (HTML) renders inside a <div>. The as prop appears as Render as in the Typography panel, not on the Properties tab.
  • Image renders one media item. See Image block variants.
  • Video plays the uploaded file as is; Plenary does not transcode, so upload files browsers can play directly. In the canvas the player is inert so clicks select it.

Details for each, including component props, are in @plenary/react built-in components.

A custom component is an ordinary React component plus a registration that tells the console what to show in the palette and which props to edit.

components/blocks/Hero.tsx
import type { ResolvedMedia } from "@plenary/react";
export interface HeroProps {
heading?: string;
showButton?: boolean;
buttonLabel?: string;
buttonUrl?: string;
backgroundImage?: ResolvedMedia | null;
}
export function Hero({ heading = "", showButton, buttonLabel, buttonUrl, backgroundImage }: HeroProps) {
const image = backgroundImage?.url || null;
return (
<section className="hero" style={image ? { backgroundImage: `url("${image}")` } : undefined}>
<h1>{heading}</h1>
{showButton && buttonLabel ? <a href={buttonUrl || "#"}>{buttonLabel}</a> : null}
</section>
);
}
lib/blocks.ts
import { register } from "@plenary/react";
import { Hero } from "@/components/blocks/Hero";
register(Hero, {
key: "hero",
label: "Hero",
category: "Marketing",
icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="4" width="18" height="16" rx="2"/></svg>',
props: [
{ key: "heading", type: "text", required: true, defaultValue: "Your headline here" },
{ key: "showButton", type: "boolean", ui: { label: "Show Button" } },
{ key: "buttonLabel", type: "text", visibleWhen: { prop: "showButton", equals: true } },
{ key: "buttonUrl", type: "url", ui: { label: "Button URL" }, visibleWhen: { prop: "showButton", equals: true } },
{ key: "backgroundImage", type: "image", ui: { show_alt_caption: false } },
],
styles: ["size", "background", "typography", "css"],
});

Import lib/blocks.ts from both your server page routes and the client module that renders the bridge. Next.js has separate server and client module graphs, and each needs the registrations. See Register in both module graphs.

Field Description
key Stored in every node as component. Do not change it once pages use it.
label Palette and tree name.
category Palette group, shown as Custom · {category}.
icon Palette icon: an image URL, a data URI, or inline SVG markup. Drawn small and monochrome.
props The editable props (below).
slots Named child regions (below).
styles Which Style-tab panels to offer (below).

A prop’s type is a content field type, and its input on the Properties tab is the same input that type uses in the entry form. Allowed types: text, rich_text, number, boolean, date, time, datetime, json, image, file, reference, email, url, select, multi_select, list, and tags. Not allowed: object, computed, blocks, phone.

settings and ui take the same shapes as a model field’s settings and UI options; see Field Types. Common cases:

lib/blocks.ts
import type { PropDefinition } from "@plenary/core";
const props: PropDefinition[] = [
// Multi-line text input with a custom label and help text.
{ key: "intro", type: "text", ui: { control: "textarea", label: "Intro", help_text: "One or two sentences." } },
// A select stores the option's value string.
{
key: "tone",
type: "select",
defaultValue: "light",
settings: { options: [{ value: "light", label: "Light" }, { value: "dark", label: "Dark" }] },
},
// A repeating group: a list of objects. Sub-fields go under settings.item_settings.fields.
{
key: "features",
type: "list",
settings: {
item_type: "object",
sortable: true,
item_settings: {
fields: [
{ key: "title", name: "Title", type: "text", required: true },
{ key: "body", name: "Body", type: "text", ui: { control: "textarea" } },
],
},
},
ui: { add_label: "Add feature", collapsible_items: true },
},
// A reference names its target model by key. Stored as { reference_id }, not hydrated.
{ key: "author", type: "reference", settings: { model: "person" } },
// A file picker limited to videos.
{ key: "clip", type: "file", ui: { media_type: "video" } },
];

What your component receives:

Prop type Value in your component
text, email, url, rich_text string (rich_text is HTML)
number, boolean number, boolean
select the option’s value string
multi_select, tags string array
list array of items
image, file a resolved media object: { url, alt, variants, width?, height?, caption?, missing? }. url is "" when unresolved
reference { reference_id } or { reference_ids }. Fetch the entry yourself
date, time, datetime, json as stored

image and file props are resolved at the top level and inside the items of a list prop, so a logo strip or a card grid can be one block with a list of items. Media nested deeper, or inside a json prop, arrives as the stored { media_id } pointer; resolve it with resolveMedia.

  • defaultValue is written into a new block’s props when an editor adds it. The renderer does not apply defaults, so existing blocks and blocks created through the API may lack the prop. Give your component a fallback (heading = "").
  • Without ui.label, the console derives a label from the key: buttonUrl becomes “Button Url”. Set ui.label for anything that reads badly.
  • required: true marks the input as required in the console.

visibleWhen: { prop, equals } shows a prop’s input only while the sibling prop prop strictly equals equals. A sibling the editor has not touched is compared by its defaultValue. Hidden props keep their stored values and still reach your component, so check the controlling prop in your component too (showButton && buttonLabel).

Declare slots to let editors put blocks inside your component:

components/blocks/Card.tsx
import type { ReactNode } from "react";
export function Card({ title, children, slots }: { title?: string; children?: ReactNode; slots?: Record<string, ReactNode> }) {
return (
<article className="card">
<h3>{title}</h3>
<div className="card__body">{children}</div>
<footer className="card__footer">{slots?.footer}</footer>
</article>
);
}
lib/blocks.ts
import { register } from "@plenary/react";
import { Card } from "@/components/blocks/Card";
register(Card, {
key: "card",
label: "Card",
props: [{ key: "title", type: "text" }],
slots: [
{ name: "children", label: "Body" },
{ name: "footer", label: "Footer" },
],
});

The children slot arrives as React children. Every other slot arrives in the slots prop as rendered React nodes. Slots are fixed per component, and any block can be dropped into any slot.

In the canvas, every component also receives editor: true. Use it for affordances that help editors but must not ship, such as a placeholder for an empty block. Published renders never set it.

It is also the reliable way to change how a component behaves on the canvas, for example to skip an intro animation, give a full-height hero a fixed height, or stop a marquee. Overriding the editor’s CSS is fragile: your component’s own stylesheet can win over it with a more specific selector, and nothing warns you when that happens.

The Style tab edits CSS for the selected block, per device.

A component’s styles array decides which panels appear:

styles value Panels
layout Layout
size Sizing, Padding, Margin
background Appearance, Border
typography Typography
css CSS Properties

Omit styles (or pass []) to offer no style controls: the console shows “This component doesn’t expose style controls.” That is a valid choice for components that must stay on-brand.

You write no styling code. The renderer removes the style props before your component sees them and emits a stylesheet that targets your component’s root element with !important. Declaring a panel is a promise that your component has a single root element.

Each block stores three style layers as props:

Viewport in the toolbar Stored in Applies at
Desktop 1280 style every width
Tablet 834 styleTablet max-width: 1024px
Mobile 390 styleMobile max-width: 640px

The viewport switcher picks the layer you edit, and the top of the Style tab names it (Editing Desktop, Tablet, or Mobile). Tablet and mobile inherit from the layers above them, per property. An amber dot marks a property set on the current layer; clear the control (or use Reset to inherit) to inherit again. Each layer is a flat camelCase record, such as { "paddingTop": "32px" }.

Change the cutoffs with registerTheme({ breakpoints: { tablet: 960, mobile: 600 } }). Keep them equal to your own stylesheet’s breakpoints.

The compiled CSS for a block looks like this:

[data-plenary-id="3f0c2b9e"] > * { color: var(--ink) !important; }
@media (max-width: 640px) { [data-plenary-id="3f0c2b9e"] > * { padding-top: 32px !important; } }

Styled blocks are wrapped in <div data-plenary-id="..." style="display: contents">, which does not affect layout. Values that could break out of the stylesheet are dropped, so the CSS is safe to inline.

Register your brand colors and fonts so editors pick from them instead of typing hex codes:

lib/blocks.ts
import { registerTheme } from "@plenary/react";
registerTheme({
colors: [
{ name: "brand", value: "#2563eb", label: "Brand" },
{ name: "ink", value: "#0f172a", label: "Ink" },
],
fonts: [{ name: "font-display", value: "Georgia, serif", label: "Display" }],
});
app/globals.css
:root {
--brand: #2563eb;
--ink: #0f172a;
--font-display: Georgia, serif;
}

Color pickers (text, background, border) offer colors first, and the Typography panel’s font picker offers fonts. Picking a token stores var(--brand), not the hex value, so changing --brand in your CSS restyles every page that uses it. value is only the swatch the console displays. Every token must exist as a CSS custom property on your site.

The built-in Image block can serve a resized copy of its image instead of the original. Its props are a one-off variant spec:

Property Prop Meaning
Max Width (px) width Output width in pixels
Max Height (px) height Output height in pixels
Quality (%) quality Encoding quality, 1 to 100
Crop to fill crop Crop to fill width × height instead of fitting inside, centered on the image’s focal point when one is set

Set at least a width or a height. When the entry is saved, the server queues the variant for generation. Reads of the entry then include media.variant_url on that Image block, and the renderer uses it as the <img> source. With no width or height, or with an invalid spec, the original is served. Identical specs on the same image share one generated file.

These are output pixels, not layout size: use the Style tab’s Sizing panel to control how large the image displays. The canvas always shows the original, because the variant is generated only after saving.

Only the built-in image block gets variants. Media props on your own components are passed through as the original plus any variants defined on the asset.

The console needs to know your components even when your site is not connected, to show the palette and property forms. Each time a preview connects, the bridge announces its manifest (every registered component and your theme), and the console stores it on the server, one per site, whenever it differs from the stored copy. When no preview is connected, the console falls back to the stored manifest.

Method and path Permission Description
GET /api/v1/page-builder/manifest?site_key={site} content:entries:read on the site The stored manifest: { "components": [...], "theme": {...}, "updated_at": "..." }
PUT /api/v1/page-builder/manifest?site_key={site} content:entries:update on the site Replace it. Body: { "components": [...], "theme": {...} }
Terminal window
curl "https://your-instance.plenarycms.io/api/v1/page-builder/manifest?site_key=default" \
-H "Authorization: Bearer $PLENARY_ACCESS_TOKEN"
{
"components": [
{
"name": "hero",
"label": "Hero",
"category": "Marketing",
"icon": "data:image/svg+xml,%3Csvg...",
"props": [{ "key": "heading", "type": "text", "required": true, "defaultValue": "Your headline here" }],
"slots": [],
"styles": ["size", "background", "typography", "css"]
}
],
"theme": { "colors": [{ "name": "brand", "value": "#2563eb", "label": "Brand" }] },
"updated_at": "2026-10-07T09:16:55.534Z"
}

The server stores component definitions as given. It rejects a manifest with more than 500 components, a component without a name, or duplicate names (manifest_components_invalid with reason too_many, name_missing, or name_duplicate), and bodies over 1 MiB (manifest_too_large). See Errors.