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

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Rich Text React Renderer

Name: tessl/npm-contentful--rich-text-react-renderer
Author: tessl

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

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 2 months ago
Describes: pkg:npm/@contentful/rich-text-react-renderer@16.0.x
Publish Source: CLI
Badge