---
id: migration-guide
description: A guide to migrate React Native Render HTML from v5 to v6.
sidebar_position: 10
---
import APIReference from '@site/src/components/APIReference';

# Migrating to v6

:::important

V6 is a brand new rewrite of the library, bringing amazing new features such as
whitespace collapsing, list style type support, and enhanced performances.
However, it will take some work to migrate your project to support the new API.

:::

## Props

:::note

A good amount of props have had their name changes, while their behavior is
similar or equivalent. The biggest endeavor will be to [migrate custom
renderers](#migrate-custom-renderers).

:::

### Props to Monitor

| Prop                      | Remarks                                                                                                                                                                                                        |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `renderers`               | Each renderer function should be converted to a React Component. See [Custom Rendering guide](./guides/custom-renderers.mdx) and the below section, [Migrating Custom Renderers](#migrating-custom-renderers). |
| `renderersProps`          | To access those props from a custom renderer, you should now use `useRendererProps` hook.                                                                                                                      |
| `source`                  | A new type of source is available, `source.dom`. See [DOM Tampering](./guides/dom-tampering.mdx#prerendering) for a use case.                                                                                  |
| `computeEmbeddedMaxWidth` | You can now take advantage of `useComputeMaxWidthForTag` hook to consume max width from custom renderers.                                                                                                      |
| `tagsStyles`              | Those styles are now mixed styles records, which are unlikely to break. See [Styling Components](./guides/styling.mdx).                                                                                        |
| `classesStyles`           | Those styles are now mixed styles records, which are unlikely to break. See [Styling Components](./guides/styling.mdx).                                                                                        |
| `allowedStyles`           | CSS properties are now camelCased.                                                                                                                                                                             |
| `ignoredStyles`           | CSS properties are now camelCased.                                                                                                                                                                             |

### Renamed and Moved Props

| v5                               | v6                                                  | Remarks                                                                                                                |
| -------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `enableExperimentalPercentWidth` | `renderersProps.img.enableExperimentalPercentWidth` |                                                                                                                        |
| `imagesInitialDimensions`        | `renderersProps.img.initialDimensions `             |                                                                                                                        |
| `onLinkPress`                    | `renderersProps.a.onPress`                          |                                                                                                                        |
| `onParsed`                       | `onTTreeUpdate`                                     | The structure has changed. See [Transient Render Engine](./flow/transient-render-engine.mdx).                          |
| `listsPrefixesRenderers`         | `customListStyleSpecs`                              | The API has changed, see [Lists, customization](./content/lists.mdx#defining-and-customizing-markers-pseudo-elements). |
| `ignoredTags`                    | `ignoredDomTags`                                    |                                                                                                                        |
| `ignoreNodesFunction`            | `ignoreDomNode`                                     |                                                                                                                        |

### Discontinued Props

| Prop                   | Remarks                                                                                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `containerStyle`       | You can use `baseStyle` instead.                                                                                                                               |
| `customWrapper`        |                                                                                                                                                                |
| `ptSize`               |                                                                                                                                                                |
| `baseFontStyle`        | You can use `baseStyle` instead.                                                                                                                               |
| `alterData`            | You can use `domVisitors.onText` instead. See [Dom Tampering](./guides/dom-tampering.mdx#example-altering-data).                                               |
| `alterChildren`        | You can use `domVisitors.onElement` instead. See [Dom Tampering](./guides/dom-tampering.mdx#example-inserting-elements).                                       |
| `alterNode`            | You can use `domVisitors.onElement` instead. See [Dom Tampering](./guides/dom-tampering.mdx#example-removing-elements).                                        |
| `allowWhitespaceNodes` | White-space collapsing is now fully supported. See [Transient Render Engine, whitespace collapsing](./flow/transient-render-engine.mdx#whitespace-collapsing). |

### Other Props

Props not listed in the above section are unchanged.

## Migrating Custom Renderers

### Arguments Equivalence

Let's start with a custom renderer from v5:

```jsx title="renderers.jsx"
const renderers = {
  hr: (htmlAttribs, children, convertedCSSStyles, passProps) => {
    return /* Whatever */;
  }
};
```

In v6, renderers are React components:

```jsx title="renderers.jsx"
const renderers = {
  hr: ({
    tnode,
    onPress,
    propsFromParent,
    sharedProps,
    style,
    textProps,
    type,
    viewProps,
    InternalRenderer,
    TDefaultRenderer
  }) => {
    return /* Whatever */;
  }
};
```

:::tip
See <APIReference name="CustomRendererProps" /> for a detail on each of these props.
:::

Let's see now how arguments map from v5 to v6:

| Argument (v5)                               | Prop Name (v6)                                | Remarks                                                                                                                                                                                                                                                                                    |
| ------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `htmlAttribs`                               | `tnode.attributes`                            | The TNode is the intermediary representation of the element to render. See [Architecture](./architecture.mdx).                                                                                                                                                                             |
| `children`                                  | Alternative exists.                           | You can still render children. However, instead of having access to the children as React elements, you can inspect `tnode.children` and render these with `TNodeChildrenRenderer`. This is much more flexible than the legacy API. See [Custom Rendering](./guides/custom-renderers.mdx). |
| `convertedCSSStyles`                        | `style`                                       | Those styles are flatten and can be easily inspected.                                                                                                                                                                                                                                      |
| `passProps.renderersProps`                  | Alternative exists.                           | You can access renderers prop for a specific tag via `useRendererProps` hook.                                                                                                                                                                                                              |
| `passProps.nodeIndex`                       | `tnode.nodeIndex`                             |                                                                                                                                                                                                                                                                                            |
| `passProps.transientChildren`               | `tnode.children`                              |                                                                                                                                                                                                                                                                                            |
| `passProps.domNode`                         | `tnode.domNode`                               |                                                                                                                                                                                                                                                                                            |
| `passProps.parentWrapper`                   | `type`                                        | Either `"text"` or `"block"`.                                                                                                                                                                                                                                                              |
| `passProps.data`                            | `tnode.data`                                  | Available when `tnode.type === 'text'`                                                                                                                                                                                                                                                     |
| `passProps.key`                             | N/A                                           | Keys don't need to be used anymore since renderers are components. The key is handled by the parent (`TNodeRenderer`).                                                                                                                                                                     |
| `passProps.parentTag`                       | `tnode.parent.tagName`                        |                                                                                                                                                                                                                                                                                            |
| `passProps.onLinkPress`                     | Alternative exists.                           | You can access this prop via `useRendererProps('a').onPress`.                                                                                                                                                                                                                              |
| `passProps.tagsStyles`                      | No Equivalent.                                |                                                                                                                                                                                                                                                                                            |
| `passProps.classesStyles`                   | No Equivalent.                                |                                                                                                                                                                                                                                                                                            |
| `passProps.defaultTextProps`                | `textProps`                                   |                                                                                                                                                                                                                                                                                            |
| `passProps`.<wbr/>`defaultWebViewProps`     | `sharedProps`.<wbr/>`defaultWebViewProps`     |                                                                                                                                                                                                                                                                                            |
| `passProps`.<wbr/>`computeEmbeddedMaxWidth` | `sharedProps`.<wbr/>`computeEmbeddedMaxWidth` | A better option is to take advantage of `useComputeMaxWidthForTag` hook.                                                                                                                                                                                                                   |
| `passProps.contentWidth`                    | Alternative exists.                           | Access content width via `useContentWidth` hook.                                                                                                                                                                                                                                           |

### Custom Tags

Let's say we registered a renderer for `<bluecircle>` tag, which is non-standard. In v6, we must also register the **element model** for this tag.
See [Custom Rendering, registering a new tag](./guides/custom-renderers.mdx#example-registering-a-new-tag).

## Other Exports

| Export                      | Remarks                                                                                                           |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `getParentsTagsRecursively` | Discontinued.                                                                                                     |
| `getClosestNodeParentByTag` | Discontinued.                                                                                                     |
| `constructStyles`           | Discontinued. Not applicable since the styling logic has been totaly reframed and should be much more consistent. |
| `domNodeToHTMLString`       | Unchanged.                                                                                                        |