RichTextViewer Reference

RichTextViewer Reference

RichTextViewer is the read-only Fabric renderer for one HTML or ProseMirror JSON source. It prepares native layout directly and does not create or use NativeEditorDocumentHandle.

The viewer is New Architecture-only. Give it a finite positive layout width; see Viewer for list sizing and error handling.

Source contract

RichTextViewerProps is an exclusive union:

Source prop	Type	Requirement
contentJSON	DocumentJSON | string	Supply this or contentHTML, but not both. A string must be serialized ProseMirror JSON, not HTML.
contentHTML	string	Supply this or contentJSON, but not both.

RichTextViewerBaseProps extends React Native ViewProps, so ordinary view props such as style and accessibility props apply to its outer view (an overlay container when atoms are registered). The named props below are the package-specific contract.

Props

Prop	Type	Status / default	Behavior
schema	SchemaDefinition	Optional; defaultSchema plus mention node	Schema used to parse and render. Give the same custom schema that produced the content. The viewer composes the standard mention node and registered atom definitions automatically.
theme	EditorTheme	Optional	Flat document style slots, with arrays supported per slot. Mention addon styling uses createMentionsAddon({ theme: { node: ... } }).
style and other ViewProps	ViewProps	Optional	Layout, background, accessibility, and other ordinary Fabric-view props forwarded through RichTextViewerBaseProps.
allowBase64Images	boolean	false	Enables the viewer configuration's data-image policy for supported HTML paths.
imageLoadingPolicy	EditorImageLoadingPolicy	Optional	Native image fetch/decode budget.
resourceLimits	EditorResourceLimits	Optional	Resource budget resolved before the viewer configuration is sent to native. Invalid values throw NativeEditorBoundaryError.
collapseTrailingEmptyParagraphs	boolean	true	Removes every trailing empty paragraph and collapses an all-empty document to zero height.
enableLinkTaps	boolean	true	Permits native link interaction when onPressLink is also supplied. Without a handler, links remain static readable text.
renderImages	boolean	true	false preserves document layout while preventing native image resource requests.
fontEnvironmentRevision	number	0	Increase when the surrounding native font environment changes and layout should be rebuilt.
addons	RichTextViewerAddons (EditorAddons)	Optional	Readonly addon array for mentions and optional code highlighting; false, null, and undefined entries are ignored.
atoms	readonly AtomNodeDefinition[]	Optional	React custom block renderers; node specs are composed into the viewer schema.
readOnly	boolean	true	Controls persisted atom updates. Prose always remains read-only.
atomsInteractive	boolean	true	Controls atom input independently of readOnly.
atomViewport	AtomViewport	Optional	{ y, height, overscan? } in viewer-content coordinates. Opts into React atom virtualization; overscan defaults to 200 points.
onUpdateAtomAttrs	(event: RichTextViewerAtomAttrsUpdateEvent) => void | Promise	Optional	Application-owned persistence; requires readOnly={false}. Supply updated content after saving.
onPressLink	(event: RichTextViewerLinkPressEvent) => void	Optional	Receives href and rendered text after a link activation.
onError	(event: RichTextViewerErrorEvent) => void	Optional	Receives viewer failures; these are callback events, not typed document-handle exceptions.

There is no contentRevision, contentJSONRevision, contentId, containerWidth, mentionPrefix, or resolveMentionTheme prop.

Events and mentions

Export	Shape / behavior
RichTextViewerLinkPressEvent	href: string; text: string. Delivered only when enableLinkTaps is true and onPressLink is supplied; only then is the link actionable to accessibility.
RichTextViewerMentionPressEvent	docPos: number; label: string; attrs: Record<string, unknown>. Delivered, and exposed as actionable, only when a mentions addon with onPress is supplied.
RichTextViewerErrorEvent	domain: string; code: string; message: string; fatal: boolean. Fatal means the source/configuration/layout generation cannot render; non-fatal failures may leave text usable.
RichTextViewerMentionsConfig	Alias of MentionsAddonOptions. Pass to createMentionsAddon(); trigger participates in parsing, prefix controls display, and theme.node styles mentions.
RichTextViewerAddons	Alias of EditorAddons: readonly EditorAddonEntry[].
RichTextViewerAtomAttrsUpdateEvent	nodeType: string; atomId?: string; docPos: number; attrs and partial: Readonly<Record<string, unknown>>. docPos is snapshot-relative; atomId comes from the definition’s idAttribute.

If native mention attrs cannot be decoded as a JSON object, the viewer calls onError with viewer / INVALID_MENTION_ATTRIBUTES and does not call the mention onPress handler.

import { createMentionsAddon } from '@apollohg/react-native-rich-text-editor';

<RichTextViewer
  contentJSON={article}
  addons={[
    createMentionsAddon({
      prefix: '@',
      onPress: ({ attrs }) => openProfile(String(attrs.userId)),
    }),
  ]}
  onPressLink={({ href }) => openExternalLink(href)}
  onError={(error) => reportViewerFailure(error)}
/>

Rendering notes

• Object JSON is serialized by the component; preserve a stable object identity when possible.
• HTML and JSON are parsed using the selected schema. Unknown custom content needs its custom schema on the viewer too.
• imageLoadingPolicy, renderImages, and allowBase64Images govern different parts of image work. See Production Limits and Errors.
• Prepared layouts are keyed by effective appearance and accessibility contrast; fontEnvironmentRevision covers font changes the view cannot observe itself.
• Accessibility nodes preserve document/inline order, heading traits, image alt text, and actionable link/mention geometry. Static links and mentions remain readable without handlers.
• Registered custom atoms mount React components; unregistered custom void nodes use native fallback rendering. Atom props include isViewer: true, selected: false, and no editor actions.
• Atom updates are controlled requests, serialized per atom. Successful callbacks acknowledge attributes for subsequent functional updates while the source remains current; rejected handlers propagate their error. A new source/configuration/width invalidates old update callbacks and queued work. See Custom Atom Nodes.
• readOnly={false} still requires an update handler. The atom receives the supplied readOnly flag even when the handler is absent, but updateAttrs then rejects with not-applicable.
• The final rendered element does not add trailing block or list spacing to the measured height.
• The viewer has no editable ref, selection callbacks, toolbar, document revision, or collaboration transport.

Related pages

• Viewer
• Schema Customization
• Mentions
• Styling
• EditorTheme Reference
• Addons
• Code Syntax Highlighting
• Custom Atom Nodes
• Types and Events Reference