react-native-render-html

The library uses an intermediary data structure called a Transient Render Tree to handle CSS whitespace collapsing and React Native constraints before final rendering. This tree is composed of TNode objects, which are categorized into four types:

• TBlock: Represents block-level content. Children can be TBlock, TPhrasing, or TEmpty. Typically rendered as a React Native <View /> (or via custom renderers).
• TPhrasing: Represents inline/phrasing content. Children can be TText, TPhrasing, or TEmpty. Typically rendered as a React Native <Text /> node, creating an inline formatting context.
• TText: Represents raw text. It cannot have children and contains the actual string data.
• TEmpty: Represents nodes that should not be rendered (e.g., <script>, <link>).

interface TNode {
    type: 'block' | 'phrasing' | 'text' | 'empty';
    attributes: Record<string, string>;
    children: TNode[];
    isAnchor: boolean;
    isCollapsibleLeft(): boolean;
    isCollapsibleRight(): boolean;
    isWhitespace(): boolean;
    isEmpty(): boolean;
    trimLeft(): void;
    trimRight(): void;
    getFirstChild(): TNode | null;
    getLastChild(): TNode | null;
}

interface TBlock extends TNode {
    type: 'block';
    tagName?: string;
}

interface TPhrasing extends TNode {
    type: 'phrasing';
    tagName?: string;
}

interface TText extends TNode {
    type: 'text';
    tagName?: string;
    data: string;
}

interface TEmpty extends TBlock {
  type: 'empty';
  tagName?: string;
}

To gain direct access to the DOM object (e.g., for extracting headings), use the explicit composite rendering architecture. This involves replacing the standard <RenderHTML /> component with <RenderHTMLSource /> and wrapping your application (or a specific subtree) in <TRenderEngineProvider /> and <RenderHTMLConfigProvider />.

Key configuration props for <TRenderEngineProvider />:

• ignoredDomTags: An array of tag names to ignore during parsing.
• selectDomRoot: A function to select the specific DOM element to serve as the rendering root.

Key configuration props for <RenderHTMLConfigProvider />:

• enableExperimentalMarginCollapsing: A boolean to enable vertical margin collapsing.

import * as React from 'react';
import {
  RenderHTMLConfigProvider,
  TRenderEngineProvider,
  TRenderEngineConfig,
} from 'react-native-render-html';
import { findOne } from 'domutils';

// Example: Select the <article> tag as the root
const selectDomRoot: TRenderEngineConfig["selectDomRoot"] = (node) =>
  findOne((e) => e.name === "article", node.children, true);

const ignoredDomTags = ["button"];

export default function WebEngine({ children }: React.PropsWithChildren<{}>) {
  return (
    <TRenderEngineProvider
      ignoredDomTags={ignoredDomTags}
      selectDomRoot={selectDomRoot}>
      <RenderHTMLConfigProvider enableExperimentalMarginCollapsing>
        {children}
      </RenderHTMLConfigProvider>
    </TRenderEngineProvider>
  );
}

To enable the Scroller to know where headings are located, you must register their layout coordinates. This is achieved by creating custom renderers for h2, h3, and header tags using react-native-render-html's custom renderer system.

1. Create a HeadingRenderer that calls scroller.registerScrollEntry inside its onLayout handler.
2. Create a HeaderRenderer that calls scroller.setOffset inside its onLayout handler to account for the header's height.
3. Pass these renderers to the RenderHTMLConfigProvider via the renderers prop.

Note: Since these tags have a block content model, they are rendered as View components, allowing you to pass onLayout via the viewProps prop to the TDefaultRenderer.

const HeadingRenderer: CustomBlockRenderer = function HeaderRenderer({
  TDefaultRenderer,
  ...props
}) {
  const scroller = useScroller();
  const onLayout = useCallback(
    (e: LayoutChangeEvent) => {
      scroller.registerScrollEntry(textContent(props.tnode.domNode!), e);
    },
    [scroller]
  );
  return <TDefaultRenderer {...props} viewProps={{ onLayout }} />;
};

const HeaderRenderer: CustomBlockRenderer = function HeaderRenderer({
  TDefaultRenderer,
  ...props
}) {
  const scroller = useScroller();
  const onLayout = useCallback(
    (e: LayoutChangeEvent) => {
      scroller.setOffset(e.nativeEvent.layout.y + e.nativeEvent.layout.height);
    },
    [scroller]
  );
  return <TDefaultRenderer {...props} viewProps={{ onLayout }} />;
};

const renderers: CustomTagRendererRecord = {
  h2: HeadingRenderer,
  h3: HeadingRenderer,
  header: HeaderRenderer,
};

To make the Scroller instance accessible throughout your component tree (e.g., to allow a Table of Contents component to trigger scrolls in a separate Article Body component), use a React Context provider.

1. Create a ScrollerProvider and a useScroller hook.
2. Wrap your screen or application with ScrollerProvider and pass the Scroller instance.
3. Consume the instance using useScroller() in child components.

import React, { createContext, PropsWithChildren, useContext } from "react";
import Scroller from './Scroller';

const scrollerContext = createContext<Scroller>(null as any);

export function useScroller(): Scroller {
  return useContext(scrollerContext);
}

export function ScrollerProvider({
  children,
  scroller
}: PropsWithChildren<{ scroller: Scroller }>) {
  return (
    <scrollerContext.Provider value={scroller}>
      {children}
    </scrollerContext.Provider>
  );
}