Skip to content

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

Terminal window
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
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.

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.

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.

lib/blocks.ts
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.

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.

lib/blocks.ts
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 },
});

Next.js builds separate server and client module graphs, and each gets its own copy of the registry. Import your registrations module from:

  1. every server route that renders a document, so the published page renders your components, and
  2. the "use client" module that renders PlenaryBridge, 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
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.

app/[slug]/page.tsx
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.

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.

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.

  • Style props never reach your component. style, styleTablet, and styleMobile are 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 image or file, and each image or file sub-field of a list prop’s items, the stored pointer is replaced with a ResolvedMedia object. Media nested deeper, or inside a json prop, is passed through as stored.
  • Slots. The children slot becomes React children. Every other slot arrives in a slots prop: 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
}

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.

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.

interface PlaceholderProps {
component: string;
}

The red dashed box the renderer shows for an unregistered component key.

/** 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.

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 renders children and does nothing else.
  • After init it announces your registered components and theme, then replaces children with 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 text blocks.
  • Everything outside the bridge (your header, footer, and layout) keeps rendering normally. Put site chrome outside the bridge.
components/PageBridge.tsx
"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