@plenary/react
@plenary/react renders Page Builder documents with React. It holds the component registry (the built-in blocks plus the components you register), the renderer that turns a PlenaryDocument into React elements, and PlenaryBridge, the component that lets the console drive a live preview of your site.
npm install @plenary/react @plenary/client @plenary/core| Version | 1.0.x |
| Peer dependencies | react and react-dom ^18 || ^19 |
| Dependencies | @plenary/core, @plenary/client (same version) |
| Module format | ESM only, with type declarations |
Entry points
Section titled “Entry points”| Import path | Contains | Server-safe |
|---|---|---|
@plenary/react |
registry, renderer, built-in components, media helpers, types | yes |
@plenary/react/bridge |
PlenaryBridge |
no: it is a client component ("use client") |
The package ships unbundled: every source file becomes its own ESM file in dist/. That keeps the "use client" directive at the top of bridge.js, so React Server Components frameworks such as the Next.js App Router treat PlenaryBridge as a client component while the renderer stays usable on the server. It also keeps @plenary/client a real import, so instanceof PlenaryNotFoundError works across packages.
Registering components
Section titled “Registering components”The registry is a module-level singleton. It starts with the built-in blocks already registered. Registering a component does two things: the renderer can resolve nodes with that component key, and the bridge announces the component to the console, which puts it in the palette.
register
Section titled “register”function register(component: PlenaryComponent, registration: ComponentRegistration): Registry;| Parameter | Type | Description |
|---|---|---|
component |
PlenaryComponent (any React component type) |
The component to render for this key |
registration |
ComponentRegistration |
Key, label, icon, category, props, slots, and style panels |
Returns the singleton Registry, so calls can chain. Registering an existing key replaces it, including a built-in.
import { register } from "@plenary/react";import { Hero } from "@/components/blocks/Hero";
register(Hero, { key: "hero", label: "Hero", category: "Marketing", props: [ { key: "heading", type: "text", required: true, defaultValue: "Your headline here" }, { key: "showButton", type: "boolean" }, { key: "buttonLabel", type: "text", visibleWhen: { prop: "showButton", equals: true } }, { key: "backgroundImage", type: "image" }, ], styles: ["size", "background", "typography", "css"],});See PropDefinition for every prop option and the Page Builder guide for a walkthrough.
registerTheme
Section titled “registerTheme”function registerTheme(theme: ThemeRegistration): Registry;Declares the design tokens the console’s style pickers offer, and optionally the breakpoint cutoffs. A later call replaces the earlier theme. Every token must exist as a CSS custom property (--<name>) in your stylesheet, because the console stores var(--<name>) references. See ThemeRegistration.
import { registerTheme } from "@plenary/react";
registerTheme({ colors: [{ name: "brand", value: "#2563eb", label: "Brand" }], fonts: [{ name: "font-display", value: "Georgia, serif", label: "Display" }], breakpoints: { tablet: 1024, mobile: 640 },});Register in both module graphs (Next.js)
Section titled “Register in both module graphs (Next.js)”Next.js builds separate server and client module graphs, and each gets its own copy of the registry. Import your registrations module from:
- every server route that renders a document, so the published page renders your components, and
- the
"use client"module that rendersPlenaryBridge, so the live preview renders them and the console’s palette lists them.
If you miss the second import, custom blocks render as “Unknown component” placeholders in the preview and never appear in the palette. The Page Builder Site example shows both imports.
Plenary, getManifest, getTheme, registry, Registry
Section titled “Plenary, getManifest, getTheme, registry, Registry”const Plenary: { register: typeof register; registerTheme: typeof registerTheme };
function getManifest(): ManifestComponent[];function getTheme(): ThemeRegistration | undefined;
const registry: Registry;
class Registry { register(component: PlenaryComponent, registration: ComponentRegistration): this; registerTheme(theme: ThemeRegistration): this; getTheme(): ThemeRegistration | undefined; get(key: string): RegisteredComponent | undefined; all(): RegisteredComponent[]; manifest(): ManifestComponent[];}| Export | Description |
|---|---|
Plenary |
Namespace form: Plenary.register(...), Plenary.registerTheme(...) |
getManifest() |
Every registered component as the console sees it: built-ins first, then yours. Inline SVG icons come back as data URIs |
getTheme() |
The registered theme, if any |
registry |
The singleton the renderer and bridge read |
Registry |
The class. A new Registry() starts with the built-ins, but the renderer and bridge only read the singleton registry |
Rendering documents
Section titled “Rendering documents”PlenaryPage
Section titled “PlenaryPage”interface PlenaryPageProps { document: PlenaryDocument; /** Client used to resolve media props (optional). */ client?: PlenaryClient;}
function PlenaryPage(props: PlenaryPageProps): Promise<ReactNode>;An async Server Component that renders a whole document. Use it in React Server Components environments such as the Next.js App Router.
import type { PlenaryDocument } from "@plenary/core";import { PlenaryPage } from "@plenary/react";import { plenary } from "@/lib/plenary";import "@/lib/blocks";
export default async function Page({ params }: { params: Promise<{ slug: string }> }) { const { slug } = await params; const entry = await plenary.getEntry<{ body?: PlenaryDocument }>("page", slug); return entry.data.body ? <PlenaryPage document={entry.data.body} client={plenary} /> : null;}Pass client whenever the document can contain media. A blocks field stores media as bare { "media_id": "..." } pointers, and the renderer needs the client to look up their URLs. A public API key can read public media.
renderDocument
Section titled “renderDocument”interface RenderContext { client?: PlenaryClient;}
function renderDocument(document: PlenaryDocument, ctx?: RenderContext): Promise<ReactNode>;What PlenaryPage calls. It makes one batched pass to fetch every referenced media item with client.getMedia, then renders synchronously. Use it directly where async components are not available (for example React 18 without a Server Components framework): await it in a loader or effect, then render the returned node.
renderDocumentSync
Section titled “renderDocumentSync”interface SyncRenderOptions { /** Pre-fetched media detail, keyed by media_id. */ mediaDetails?: Map<string, MediaDetail>; /** Media ids known to be deleted. */ missingMedia?: Set<string>; /** Wrap every node in a data-plenary-id marker (preview mode). */ annotate?: boolean; /** Per-node remount counters used by the bridge after inline edits. */ remountKeys?: ReadonlyMap<string, number>;}
function renderDocumentSync(document: PlenaryDocument, opts?: SyncRenderOptions): ReactNode;Renders from already-resolved inputs with no fetching. Media values that already carry a url render; bare media_ids with no entry in mediaDetails render unresolved. The bridge uses this, because the console pushes media already resolved.
What the renderer does
Section titled “What the renderer does”- Style props never reach your component.
style,styleTablet, andstyleMobileare removed from the props and compiled into one<style data-plenary-styles>element placed before the tree. Each rule targets[data-plenary-id="<id>"] > *and every declaration is!important, so editor styles outrank your component’s inline styles. - Wrapper elements. A node with editor styles is wrapped in
<div data-plenary-id="<id>" style="display: contents">, which does not affect layout. In preview (annotate) mode every node is wrapped, so clicks can be mapped back to blocks. - Media props are resolved. For each prop declared as
imageorfile, and eachimageorfilesub-field of alistprop’s items, the stored pointer is replaced with aResolvedMediaobject. Media nested deeper, or inside ajsonprop, is passed through as stored. - Slots. The
childrenslot becomes Reactchildren. Every other slot arrives in aslotsprop:Record<string, ReactNode>of already-rendered nodes. - Preview flag. In preview renders every component also receives
editor: true. Use it to show editor-only affordances, such as a placeholder for an empty block, that must not appear on the published page. - No defaults. Registration
defaultValues are not merged in. Props arrive exactly as stored. - Unknown components render a visible
Placeholder(“Unknown component: key”) instead of throwing. - Suspense. The tree is wrapped in
<Suspense>, so lazy components (React.lazy,next/dynamic) work during server rendering.
So a custom component receives props shaped like this:
import type { ReactNode } from "react";import type { ResolvedMedia } from "@plenary/react";
interface HeroProps { heading?: string; // as stored backgroundImage?: ResolvedMedia | null; // an `image` prop, resolved children?: ReactNode; // the "children" slot, if declared slots?: Record<string, ReactNode>; // any other declared slots editor?: boolean; // true only in the live preview}Built-in components
Section titled “Built-in components”Five blocks are registered before your code runs. Each is also exported, so you can use it directly in your own components.
| Key | Export | Category | Props | Slots | Style panels |
|---|---|---|---|---|---|
box |
Box |
Layout | className |
children |
layout, size, background, css |
section |
Section |
Layout | columns (default 1), gap (default 16), className |
"0" to "5", one per column |
size, background, css |
text |
Text |
Content | content (rich_text), as (select, default p) |
none | size, typography, css |
image |
Image |
Content | media (image), alt, width, height, quality, crop |
none | size, css |
video |
Video |
Content | media (file, video only), poster (image), controls (default true), autoplay, loop, muted, playsinline (default true), preload (default metadata) |
none | size, css |
interface BoxProps { as?: ElementType; // default "div" className?: string; style?: CSSProperties; children?: ReactNode;}A generic container. The console seeds new boxes with a flex column style.
Section
Section titled “Section”interface SectionProps { columns?: number; // 1 to 6, default 1 gap?: number | string; // default 16 className?: string; style?: CSSProperties; slots?: Record<string, ReactNode>;}Renders a flex row of columns equal cells. Each cell is a <div data-plenary-column="i"> that shows the slot keyed String(i). columns is clamped to 1 to 6.
interface TextProps { content?: string; as?: ElementType; // default "p" className?: string; style?: CSSProperties;}Plain text renders inside the element named by as (p, h1 to h6, span, or code in the console). If content contains an HTML tag, as rich text from the console’s editor does, it renders as HTML inside <div class="plenary-text--rich"> and as is ignored. The SDK does not sanitize that HTML.
interface ImageProps { media?: ResolvedMedia | MediaValue | null; alt?: string; className?: string; style?: CSSProperties; editor?: boolean;}Renders an <img>. The source is the block’s one-off variant (media.variant_url, generated by the server from the block’s width, height, quality, and crop props) when present, otherwise the original. alt falls back to the media’s alt text. With no media it renders nothing on the published page and a placeholder in the preview. A reference to a deleted asset renders nothing published and an “Image not found” placeholder in the preview.
interface VideoProps { media?: ResolvedMedia | MediaValue | null; poster?: ResolvedMedia | MediaValue | null; controls?: boolean; autoplay?: boolean; loop?: boolean; muted?: boolean; playsinline?: boolean; preload?: "none" | "metadata" | "auto"; className?: string; style?: CSSProperties; editor?: boolean;}Renders an HTML5 <video> of the uploaded file, with no transcoding, and a default max-width: 100%; height: auto. In the preview the player is inert (no controls, no autoplay) so clicks select the block. Browsers only autoplay muted video.
Placeholder
Section titled “Placeholder”interface PlaceholderProps { component: string;}The red dashed box the renderer shows for an unregistered component key.
Media helpers
Section titled “Media helpers”/** A media prop as stored in a document. */interface MediaValue { media_id?: string; alt?: string; caption?: string; url?: string; variants?: Record<string, string>; variant_url?: string; width?: number; height?: number; missing?: boolean;}
/** What a component receives for an `image` or `file` prop. */interface ResolvedMedia { media_id?: string; /** "" when the media could not be resolved. */ url: string; alt: string; /** Ready variant URLs keyed by variant name. */ variants: Record<string, string>; variant_url?: string; caption?: string; width?: number; height?: number; /** The asset was deleted; every URL is dropped. */ missing?: boolean;}
function resolveMedia(value: MediaValue | null | undefined, client?: PlenaryClient): Promise<ResolvedMedia | null>;
function toResolvedMedia( value: MediaValue | null | undefined, detail?: MediaDetail | null, missing?: boolean,): ResolvedMedia | null;| Function | Description |
|---|---|
resolveMedia |
Resolves one value. A value that already has a url is used as is. A bare media_id is fetched with client.getMedia. A 404 resolves to missing: true; any other failure resolves to an empty url rather than throwing. Returns null for an empty value. |
toResolvedMedia |
The pure, synchronous merge of a stored value and an already-fetched MediaDetail. |
Treat url === "" as “no image”. Media URLs are paths on your Plenary instance (/media/{media_id}/{file}), not absolute URLs. Serve them from your site’s origin by proxying /media/* to the instance, as the example’s next.config.ts does, or prefix them with your instance URL.
PlenaryBridge
Section titled “PlenaryBridge”import { PlenaryBridge } from "@plenary/react/bridge";
interface PlenaryBridgeProps { /** The key of the blocks field this bridge renders from the draft. */ region: string; /** Console origins allowed to drive this preview. */ editorOrigins: string[]; /** Reported to the console in the hello handshake. Default "0.0.0". */ sdkVersion?: string; /** The normal page content, shown until a console connects. */ children?: ReactNode;}
function PlenaryBridge(props: PlenaryBridgeProps): JSX.Element;| Prop | Required | Description |
|---|---|---|
region |
yes | The blocks field key, such as "body". One bridge renders one region. |
editorOrigins |
yes | Exact origins or wildcard patterns (https://*.example.com, http://localhost:*) of the consoles allowed to drive the preview. See editor-origin matching. Never *. |
sdkVersion |
no | Informational; sent in hello. |
children |
no | Your published render of the page. |
Behavior:
- Outside an iframe, or before a console from an allowed origin sends
init, it renderschildrenand does nothing else. - After
initit announces your registered components and theme, then replaceschildrenwith the draft document the console pushes, re-rendering on every edit. - While connected it cancels link clicks and form submits inside the frame, draws selection and hover outlines, resolves palette drops, forwards editor shortcuts and zoom/pan gestures, reports the page height, and supports double-click inline editing of plain-text
textblocks. - Everything outside the bridge (your header, footer, and layout) keeps rendering normally. Put site chrome outside the bridge.
"use client";
import type { ReactNode } from "react";import { PlenaryBridge } from "@plenary/react/bridge";import "@/lib/blocks";
export function PageBridge({ editorOrigins, children }: { editorOrigins: string[]; children: ReactNode }) { return ( <PlenaryBridge region="body" editorOrigins={editorOrigins}> {children} </PlenaryBridge> );}@plenary/react exports no hooks. The draft data is only available to the components the bridge renders, through their props.
| Type | Definition |
|---|---|
PlenaryComponent |
ComponentType<any> |
RegisteredComponent |
{ registration: ComponentRegistration; component: PlenaryComponent } |
RenderContext |
{ client?: PlenaryClient } |
SlotProps |
{ slots?: Record<string, ReactNode> } |
BoxProps, SectionProps, TextProps, ImageProps, VideoProps, PlaceholderProps |
Built-in component props (above) |
MediaValue, ResolvedMedia |
Media helpers |
PlenaryPageProps, SyncRenderOptions |
Rendering documents |
PlenaryBridgeProps |
From @plenary/react/bridge |
Related
Section titled “Related”- @plenary/core: document, registration, and protocol types
- @plenary/client: the content client passed as
client - Page Builder guide
- Live Preview guide
- Page Builder Site example