Rich content

Prezly content is a tree of elements and text leaves. Paragraphs and headings contain text; blocks such as images and attachments carry additional data. Render those structures rather than treating every node as a paragraph or concatenating their text.

See Story rendering for fetching and rendering a real story. This guide explains what the renderer receives and where you may need to customize it.

Read the document treeCopy Anchor Link

This small v6 document includes title and subtitle roles, inline marks, and a callout:

{
  "type": "document",
  "version": "2.6",
  "children": [
    {
      "type": "heading-one",
      "role": "title",
      "children": [{ "text": "Acme launches its new collection" }]
    },
    {
      "type": "heading-two",
      "role": "subtitle",
      "children": [{ "text": "Designed for everyday use" }]
    },
    {
      "type": "paragraph",
      "children": [
        { "text": "Meet the " },
        { "text": "new collection", "bold": true },
        { "text": ". Available from today.", "highlighted": true }
      ]
    },
    {
      "type": "callout",
      "icon": "💡",
      "children": [{ "text": "Press images are available below." }]
    }
  ]
}

An element has a type, children, and properties specific to that type. A text leaf has text and may carry marks such as bold, italic, underlined, or highlighted. Empty text children can be part of a valid node; an image or attachment does not become empty just because its text is empty.

The content-format package provides the current types and node helpers. Node-specific properties matter: an image's uploaded-file object cannot be replaced with an arbitrary remote URL.

Support the blocks your authors useCopy Anchor Link

The default React renderer does not replace your application's routing or every resource lookup. For example, coverage rendering accepts coverageEntries; linked story cards may need a custom component and the story's referenced_entities. Bea demonstrates these integrations in its ContentRenderer.

Do not silently discard unknown blocks when content or package versions advance. Choose a useful fallback, report the unsupported node type, and check whether the renderer needs an update.

Customize one node without replacing the rendererCopy Anchor Link

Use Component rules to override a node type while retaining the default components for the rest. For example, if your page already displays the title and subtitle separately, this component renders the remaining document without duplicating them:

'use client';

import { Component, Elements, Renderer } from '@prezly/content-renderer-react-js';
import { DocumentNode, HeadingNode, HtmlNode } from '@prezly/story-content-format';

export function StoryBody({ document }: { document: DocumentNode }) {
  return (
    <Renderer nodes={document}>
      <Component match={HeadingNode.isTitleHeadingNode} component={Elements.Ignore} />
      <Component match={HeadingNode.isSubtitleHeadingNode} component={Elements.Ignore} />
      <Component match={HtmlNode.isHtmlNode} component={Elements.Ignore} />
    </Renderer>
  );
}

These overrides do not suppress the header image. If your page renders that separately too, identify the document's header node and handle it deliberately rather than removing every image.

When adding broader custom heading rules, put title/subtitle rules first: the more specific match should take precedence. The renderer package exposes the default Elements for reuse.

Decide how to handle HTML and external embedsCopy Anchor Link

Structured text is rendered as text, but an html node contains raw markup. The default HTML component inserts that markup into the page. The examples above omit HTML nodes; an application that allows them should sanitize or otherwise constrain the markup before rendering it. Parsing JSON is not HTML sanitization.

External video and embed providers may load third-party scripts, frames, or cookies. Integrate them with your site's consent policy and provide a link or preview when an embed is unavailable. A restrictive content policy should give readers a useful alternative rather than an unexplained blank space.

Keep rendering separate from authoringCopy Anchor Link

Rendering reads existing documents. Creating a document requires valid node properties and uploaded media references; a renderer does not upload files, resolve every embed URL, or save stories. See Images and files for the media representation. Continue with Creating and updating stories for structured documents, or Importing HTML for existing articles.