Page Builder Documentation

What the Visual Builder does#

The Visual Builder lets editors compose a page from ordered blocks while developers retain control over the rendered UI. It is the meeting point between CMS content and your React component system.

Shared responsibility

Editors: choose blocks, enter content, arrange blocks, save drafts, preview, publish
Developers: define component types, build React components, register codes, style and test output
Contoprix: deliver the page, block data, layouts, and preview metadata

A simple marketing page could contain a hero_banner component, a content-list block of featured articles, and a call_to_action component. The editor chooses their order; the application renders each block through its matching component.

The building blocks#

A delivered page contains blocks in page.blocks. Each block has a kind, a component code, a sortOrder, an optional regionCode, and data.

Kind	CMS meaning	React prop to use
`component`	A configurable visual component type.	`settings`
`content-single`	One selected content entry.	`content`
`content-list`	A selected list of content entries.	`contents`
`form`	A form placed on a page.	`form` reference

A content entry's custom fields live in entry.data. For example, a blog-post list component reads entry.data.title, not entry.title.

What happens at render time#

PageRenderer takes the full ContoprixPage plus your component registry.

The smallest render call

import { PageRenderer } from "@contoprix/react/client";

<PageRenderer page={page} components={components} />

It sorts blocks by sortOrder and renders:

global header blocks, when page.layout.header exists;
page blocks, either in regionLayout regions or as one flat sequence;
global footer blocks, when page.layout.footer exists.

A region layout may define a grid and regions such as main and sidebar. Blocks with a regionCode render in the matching region. When no region layout is delivered, the renderer uses the simple top-to-bottom order.

How a block finds its UI#

PageRenderer delegates each block to BlockRenderer. It resolves blocks in this order:

Priority	Result
1	A custom component in your `ComponentRegistry` for `block.component`.
2	For an unregistered `component` block with a known renderable schema, the SDK's generic renderer.
3	A visible missing-component placeholder. This is the fallback for unknown components and unregistered form/content blocks.

The generic renderer is useful while a component type is new, but it is intentionally a basic fallback. Use a custom component for production design, complex layouts, forms, and content-entry placements.

Important

A code is the contract between the CMS and the frontend. If the CMS block is hero_banner, the registry key must be exactly hero_banner.

A beginner-friendly example#

An editor creates a page with these blocks:

Editor view

1. hero_banner
2. feature_grid
3. blog_post-list
4. call_to_action

The frontend registry contains custom components for hero_banner, feature_grid, and call_to_action. The blog_post-list component receives contents and renders article cards from each entry's data.

The editor can rearrange the blocks or edit their fields. The developer can improve spacing, typography, responsive behavior, accessibility, and loading states without making editors recreate content.

Visual editing versus normal preview#

Normal delivery renders published content for visitors.
Preview renders draft content for authorized editors.
Visual editing is the optional in-iframe editing layer on a preview page. It can select blocks, request insertions, move, duplicate, and delete placements, then refresh when the CMS changes the draft.

Visual editing does not make a draft public. It works only when the preview page is fetched by pageId and has a preview versionId.

Recommended first implementation#

Create one simple Component Type in the CMS, such as hero_banner.
Add a small React component for it.
Register the code in one shared registry.
Fetch a published page by slug and render it with PageRenderer.
Add schema fallback so new component types have a useful temporary UI.
Configure a protected preview URL with [pageId].
Test the component in preview and published delivery.

The next guides walk through each step.

Key practices#

Keep blocks focused on one presentational responsibility.
Use Content Types for independent records such as articles, products, and authors.
Use Component Types for reusable page presentation.
Make optional values truly optional in React.
Use real semantic HTML and accessible labels.
Test a page containing every important block before publishing it.
Re-pull the schema after model changes and validate component coverage.