Skip to main content

TRenderEngineConfig

export
interface TRenderEngineConfig {
  allowedStyles?: CSSPropertyNameList;
  baseStyle?: MixedStyleDeclaration;
  classesStyles?: Readonly<Record<string, MixedStyleDeclaration>>;
  customHTMLElementModels?: HTMLElementModelRecord;
  dangerouslyDisableHoisting?: boolean;
  dangerouslyDisableWhitespaceCollapsing?: boolean;
  domVisitors?: DomVisitorCallbacks;
  emSize?: number;
  enableCSSInlineProcessing?: boolean;
  enableUserAgentStyles?: boolean;
  fallbackFonts?: FallbackFontsDefinitions;
  htmlParserOptions?: ParserOptions;
  idsStyles?: Readonly<Record<string, MixedStyleDeclaration>>;
  ignoreDomNode?: (node: Node, parent: NodeWithChildren) => unknown;
  ignoredDomTags?: Array<string>;
  ignoredStyles?: CSSPropertyNameList;
  selectDomRoot?: (node: NodeWithChildren) => any;
  setMarkersForTNode?: SetMarkersForTNode;
  systemFonts?: Array<string>;
  tagsStyles?: Readonly<Record<string, MixedStyleDeclaration>>;
}
Defined in packages/render-html/src/shared-types.ts

Configuration for the ​TRenderEngineProvider component.

warning

When one of these props changes, it will cause the ​TRenderEngine to be rebuilt, and all transient trees to be re-assembled. Beware!

Fields#

allowedStyles#

optional
allowedStyles?: CSSPropertyNameList;

Whitelist specific inline CSS style properties and ignore the others.

warning

Property names must be camelCased: for example, background-color should be written backgroundColor.

baseStyle#

optional
baseStyle?: MixedStyleDeclaration;

The default style for the document (root). Inheritable styles will be transferred to children. That works also for textual styles.

Remarks

Any fontFamily used in those styles must be registered with ​systemFonts prop.

warning

Do NOT use the StyleSheet API to create those styles.

classesStyles#

optional
classesStyles?: Readonly<Record<string, MixedStyleDeclaration>>;

Provide mixed styles to target elements selected by CSS classes.

Remarks

Any fontFamily used in those styles must be registered with ​systemFonts prop.

warning

Do NOT use the StyleSheet API to create those styles.

customHTMLElementModels#

optional
customHTMLElementModels?: HTMLElementModelRecord;

Customize element models for target tags.

dangerouslyDisableHoisting#

optional
dangerouslyDisableHoisting?: boolean;

Experimental

Disable hoisting. Especially useful for rendering with react-native-web. Note that your layout might break in native!

Default: false

dangerouslyDisableWhitespaceCollapsing#

optional
dangerouslyDisableWhitespaceCollapsing?: boolean;

Experimental

Disable whitespace collapsing. Especially useful if your html is being pre-processed server-side with a minifier.

Default: false

domVisitors#

optional
domVisitors?: DomVisitorCallbacks;

An object which callbacks will be invoked when a DOM element or text node has been parsed and its children attached. This is great to tamper the dom, remove children, insert nodes, change text nodes data... etc.

emSize#

optional
emSize?: number;

The default value in pixels for 1em.

enableCSSInlineProcessing#

optional
enableCSSInlineProcessing?: boolean;

Enable or disable inline CSS processing of inline styles.

Default: true

Remarks

If you want to allow or disallow specific properties, use allowedStyles or ignoredStyles props.

enableUserAgentStyles#

optional
enableUserAgentStyles?: boolean;

Enable or disable fallback styles for each tag. For example, pre tags will have whiteSpace set to 'pre' by default.

Default: true

fallbackFonts#

optional
fallbackFonts?: FallbackFontsDefinitions;

A record for specific CSS fonts.

Remarks

Use Plaform.select({ ios: ..., android: ..., default: ...}).

htmlParserOptions#

optional
htmlParserOptions?: ParserOptions;

ParserOptions for htmlparser2.

Default: { decodeEntities: true }

idsStyles#

optional
idsStyles?: Readonly<Record<string, MixedStyleDeclaration>>;

Provide mixed styles to target elements identified by the id attribute.

Remarks

Any fontFamily used in those styles must be registered with ​systemFonts prop.

warning

Do NOT use the StyleSheet API to create those styles.

ignoreDomNode#

optional
ignoreDomNode?: (node: Node, parent: NodeWithChildren) => unknown;

Ignore specific DOM nodes.

Returns: true if this node should not be included in the DOM, anything else otherwise.

Remarks
  • The function is applied during DOM parsing, thus with very little overhead. However, it means that one node next siblings won't be available since it has not yet been parsed.
  • Use ignoredDomTags if you just need to target specific tag names.
warning

When this function is invoked, the node has not yet been attached to its parent or siblings. Use the second argument (parent) if you need to perform logic based on parent.

ignoredDomTags#

optional
ignoredDomTags?: Array<string>;

A list of lowercase tags which should not be included in the DOM.

ignoredStyles#

optional
ignoredStyles?: CSSPropertyNameList;

Blacklist specific inline CSS style properties and allow the others.

Remarks

Note that if you don't want inline style processing at all, you should set enableCSSInlineProcessing prop to false.

warning

Property names must be camelCased: for example, background-color should be written backgroundColor.

selectDomRoot#

optional
selectDomRoot?: (node: NodeWithChildren) => any;

Select the DOM root before TTree generation. For example, you could iterate over children until you reach an article element and return this element.

Remarks

Applied after DOM parsing, before normalization and TTree construction. Before normalization implies that a body will be added in the tree after selecting root.

setMarkersForTNode#

optional
setMarkersForTNode?: SetMarkersForTNode;

Set custom markers from a ​TNode and all its descendants. ​Markers will be accessible in custom renderers via tnode.markers prop.

Default: () => null

systemFonts#

optional
systemFonts?: Array<string>;

A list of fonts available in the current platform. These fonts will be used to select the first match in CSS fontFamily property, which supports a comma-separated list of fonts. By default, a handful of fonts are selected per platform.

Remarks
  • You need to specify any font family you wish to use via *styles props here, otherwise those styles will be ignored.
  • If you are using expo, you should use or extend Constants.systemFonts.

Example#

import RenderHTML, {defaultSystemFonts} from 'react-native-render-html'
// Replace defaultSystemFonts with Constants.systemFonts if you're using expo
const systemFonts = [...defaultSystemFonts, 'Mysuperfont']
// ...
<RenderHTML systemFonts={systemFonts} ... />

tagsStyles#

optional
tagsStyles?: Readonly<Record<string, MixedStyleDeclaration>>;

Provide mixed styles to target HTML tag names.

Remarks

Any fontFamily used in those styles must be registered with ​systemFonts prop.

warning

Do NOT use the StyleSheet API to create those styles.