or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-contentful--rich-text-react-renderer

React renderer for Contentful rich text field type that converts rich text AST documents into React components

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/@contentful/rich-text-react-renderer@16.0.x

To install, run

npx @tessl/cli install tessl/npm-contentful--rich-text-react-renderer@16.0.0

Rich Text React Renderer

React renderer for Contentful's rich text field type that converts rich text AST (Abstract Syntax Tree) documents into React components. It provides a flexible rendering system with customizable renderers for different node types (blocks, inlines) and text marks, enabling developers to override default HTML output with custom React components.

Package Information

Package Name: @contentful/rich-text-react-renderer
Package Type: npm
Language: TypeScript
Installation: npm install @contentful/rich-text-react-renderer

Core Imports

import { documentToReactComponents } from "@contentful/rich-text-react-renderer";
import type { Options, RenderNode, RenderMark, RenderText, CommonNode } from "@contentful/rich-text-react-renderer";

// Import node and mark type constants from rich-text-types
import { BLOCKS, INLINES, MARKS } from "@contentful/rich-text-types";

For CommonJS:

const { documentToReactComponents } = require("@contentful/rich-text-react-renderer");
const { BLOCKS, INLINES, MARKS } = require("@contentful/rich-text-types");

Basic Usage

import { documentToReactComponents } from "@contentful/rich-text-react-renderer";

const document = {
  nodeType: "document",
  data: {},
  content: [
    {
      nodeType: "paragraph",
      data: {},
      content: [
        {
          nodeType: "text",
          value: "Hello world!",
          marks: [],
          data: {},
        },
      ],
    },
  ],
};

// Basic rendering with default renderers
const reactComponents = documentToReactComponents(document);
// Returns: <p>Hello world!</p>

Capabilities

Document Rendering

Main function to serialize a Contentful Rich Text document to React tree with optional custom renderers.

/**
 * Serialize a Contentful Rich Text document to React tree
 * @param richTextDocument - The Contentful rich text document to render
 * @param options - Optional configuration for custom rendering
 * @returns React components tree or null if no document provided
 */
function documentToReactComponents(
  richTextDocument: Document,
  options?: Options
): ReactNode;

Usage with Custom Renderers:

import { BLOCKS, MARKS } from "@contentful/rich-text-types";
import { documentToReactComponents } from "@contentful/rich-text-react-renderer";

const options = {
  renderMark: {
    [MARKS.BOLD]: (text) => <strong className="font-bold">{text}</strong>,
  },
  renderNode: {
    [BLOCKS.PARAGRAPH]: (node, children) => (
      <p className="my-paragraph">{children}</p>
    ),
    [BLOCKS.EMBEDDED_ENTRY]: (node) => {
      const { title, description } = node.data.target.fields;
      return (
        <div className="embedded-entry">
          <h3>{title}</h3>
          <p>{description}</p>
        </div>
      );
    },
  },
  renderText: (text) => text.replace("!", "?"),
  preserveWhitespace: true,
};

const reactComponents = documentToReactComponents(document, options);

Custom Text Processing

Custom text rendering with whitespace preservation support.

/**
 * Custom text renderer function interface
 * @param text - The text content to render
 * @returns React node representation of the text
 */
interface RenderText {
  (text: string): ReactNode;
}

Usage for Line Break Handling:

const options = {
  renderText: (text) => {
    return text.split('\n').reduce((children, textSegment, index) => {
      return [...children, index > 0 && <br key={index} />, textSegment];
    }, []);
  },
};

Whitespace Preservation

Preserves multiple spaces and line breaks in rich text content.

const options = {
  preserveWhitespace: true,
};

const document = {
  nodeType: "document",
  content: [
    {
      nodeType: "paragraph",
      content: [
        {
          nodeType: "text",
          value: "Hello     world!",
          marks: [],
        },
      ],
    },
  ],
};

documentToReactComponents(document, options);
// Returns: <p>Hello&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;world!</p>

Configuration Types

Options Interface

Main configuration object for customizing rendering behavior.

interface Options {
  /** Node renderers for blocks and inlines */
  renderNode?: RenderNode;
  /** Mark renderers for text formatting */
  renderMark?: RenderMark;
  /** Text renderer for processing text nodes */
  renderText?: RenderText;
  /** Keep line breaks and multiple spaces */
  preserveWhitespace?: boolean;
}

Node Renderer Types

Custom renderer interfaces for different content types.

/**
 * Function interface for custom node renderers
 * @param node - The block or inline node to render
 * @param children - Rendered children React nodes
 * @returns React node representation
 */
interface NodeRenderer {
  (node: Block | Inline, children: ReactNode): ReactNode;
}

/**
 * Object mapping node types to custom renderer functions
 */
interface RenderNode {
  [k: string]: NodeRenderer;
}

/**
 * Object mapping mark types to custom mark renderer functions
 */
interface RenderMark {
  [k: string]: (text: ReactNode) => ReactNode;
}

Common Node Types

Union type for all supported rich text node types.

/**
 * Union type for all supported node types in rich text documents
 */
type CommonNode = Text | Block | Inline;

Supported Node Types

Block Types (via @contentful/rich-text-types)

The renderNode keys support the following BLOCKS constants:

BLOCKS.DOCUMENT - Root document container
BLOCKS.PARAGRAPH - Paragraph text block
BLOCKS.HEADING_1 through BLOCKS.HEADING_6 - Heading levels 1-6
BLOCKS.UL_LIST - Unordered list
BLOCKS.OL_LIST - Ordered list
BLOCKS.LIST_ITEM - List item
BLOCKS.QUOTE - Blockquote
BLOCKS.HR - Horizontal rule
BLOCKS.TABLE - Table container
BLOCKS.TABLE_ROW - Table row
BLOCKS.TABLE_HEADER_CELL - Table header cell
BLOCKS.TABLE_CELL - Table data cell
BLOCKS.EMBEDDED_ENTRY - Embedded entry (block-level)
BLOCKS.EMBEDDED_ASSET - Embedded asset (block-level)
BLOCKS.EMBEDDED_RESOURCE - Embedded resource (block-level)

Inline Types (via @contentful/rich-text-types)

The renderNode keys support the following INLINES constants:

INLINES.EMBEDDED_ENTRY - Embedded entry (inline)
INLINES.EMBEDDED_RESOURCE - Embedded resource (inline)
INLINES.HYPERLINK - Standard hyperlink
INLINES.ENTRY_HYPERLINK - Link to Contentful entry
INLINES.ASSET_HYPERLINK - Link to Contentful asset
INLINES.RESOURCE_HYPERLINK - Link to Contentful resource

Mark Types (via @contentful/rich-text-types)

The renderMark keys support the following MARKS constants:

MARKS.BOLD - Bold text formatting
MARKS.ITALIC - Italic text formatting
MARKS.UNDERLINE - Underline text formatting
MARKS.CODE - Inline code formatting
MARKS.SUPERSCRIPT - Superscript text formatting
MARKS.SUBSCRIPT - Subscript text formatting
MARKS.STRIKETHROUGH - Strikethrough text formatting

Default Renderers

The package provides sensible default HTML renderers for all supported node and mark types:

Block nodes: Render as corresponding HTML elements (h1-h6, p, ul, ol, li, blockquote, hr, table elements)
Inline nodes: Render as anchor tags for links, placeholder spans for embedded content
Marks: Render as corresponding HTML formatting elements (b, i, u, code, sup, sub, s)

Key Handling

When using custom renderers, avoid passing index-like keys (e.g., 1 or "1") as they may clash with default key generation. Append non-numeric characters to custom keys:

const options = {
  renderMark: {
    [MARKS.BOLD]: (text) => <b key={`${text}-key`}>{text}</b>,
  },
};

Dependencies

@contentful/rich-text-types (^17.0.1): Provides type definitions for Document, Block, Inline, Text, Mark, and constants
React (peer dependency): ^16.8.6 || ^17.0.0 || ^18.0.0 || ^19.0.0
React DOM (peer dependency): ^16.8.6 || ^17.0.0 || ^18.0.0 || ^19.0.0