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.

Props to Monitor#

Prop	Remarks
`renderers`	Each renderer function should be converted to a React Component. See Custom Rendering guide and the below section, 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 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.
`classesStyles`	Those styles are now mixed styles records, which are unlikely to break. See Styling Components.
`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.
`listsPrefixesRenderers`	`customListStyleSpecs`	The API has changed, see Lists, customization.
`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.
`alterChildren`	You can use `domVisitors.onElement` instead. See Dom Tampering.
`alterNode`	You can use `domVisitors.onElement` instead. See Dom Tampering.
`allowWhitespaceNodes`	White-space collapsing is now fully supported. See Transient Render Engine, 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:

renderers.jsx

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

In v6, renderers are React components:

renderers.jsx

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

tip

See 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.
`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.
`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`.`defaultWebViewProps`	`sharedProps`.`defaultWebViewProps`
`passProps`.`computeEmbeddedMaxWidth`	`sharedProps`.`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.

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.