RichTextEditor Reference

RichTextEditor Reference

RichTextEditor is the interactive React Native view for one shared NativeEditorDocumentHandle. Create the handle before render, keep it stable for the document lifetime, and destroy it from that owner. Initialization, schema, engine policy, and creation-time limits belong to the handle, not to this component.

See Getting Started for the smallest setup, Content and State for controlled content, and Collaboration for a room-backed handle.

Props

All props below are declared by RichTextEditorProps. The component also accepts no legacy initialContent, initialJSON, schema, maxLength, resourceLimits, allowBase64Images, readOnly, inputFilter, or autoDetectLinks props.

Prop	Type	Status / default	Behavior
accessibilityLabel	string	Optional	Accessible name for the native editable control.
accessibilityHint	string	Optional	Extra accessibility guidance for the native editable control.
documentHandle	NativeEditorDocumentHandle	Required	The one shared document session. The component verifies that it was created by createNativeEditorDocumentHandle.
documentRevision	string | null	Optional	Revision signal, normally the value in collaboration.editorBindings. When it advances, the editor re-reads the authoritative engine document.
value	string	Optional	Controlled HTML. It takes precedence over valueJSON; external changes are applied through the handle.
valueJSON	DocumentJSON	Optional	Controlled ProseMirror JSON when value is absent. It is normalized against the handle schema before use.
valueJSONRevision	string	Optional	Stable revision hint for a controlled JSON value. Use it to avoid serializing an equivalent recreated object on every render.
valueJSONUpdateMode	replace | reset	replace	replace creates an undoable replacement boundary; reset discards pending native input/composition, authoritatively replaces content, and clears history.
placeholder	string	Optional	Empty-editor hint text. theme.placeholder controls its typography and color within the first block’s content insets.
editable	boolean	true	Per-view interaction gate. false prevents mutations from this view, while controlled updates and selection flow remain possible. It does not change the handle policy.
autoFocus	boolean	false	Requests focus when the native view mounts.
autoCapitalize	none | sentences | words | characters	native editor default (sentences)	Native keyboard capitalization mode.
autoCorrect	boolean	platform editor default	Native keyboard autocorrection setting.
keyboardType	RichTextEditorKeyboardType	platform default	Native keyboard layout. See the input values below.
androidInputOptions	RichTextEditorAndroidInputOptions	Optional	Android-only input-method options. privateImeOptions is passed to the focused IME and ignored on other platforms.
heightBehavior	fixed | autoGrow	autoGrow	fixed scrolls inside the editor; autoGrow changes the view height to fit content.
showToolbar	boolean	true	Shows the configured formatting toolbar while editing.
toolbarPlacement	keyboard | inline	keyboard	keyboard uses the platform native toolbar above the keyboard. inline uses the React EditorToolbar below the editor view.
toolbarItems	readonly EditorToolbarItem[]	DEFAULT_EDITOR_TOOLBAR_ITEMS	Ordered item configuration. Schema capability and supplied callbacks decide whether a button is enabled.
onToolbarAction	(key: string) => void	Optional	Receives an action item key. Action items are application behavior, not engine commands.
onRequestLink	(context: LinkRequestContext) => void	Optional	Called by a link item. The host collects a URL and calls the captured context method.
onRequestImage	(context: ImageRequestContext) => void	Optional	Called by an image item. The host chooses or uploads a source and calls insertImage.
imageLoadingPolicy	EditorImageLoadingPolicy	Optional	Per-view budget for native data-URL and remote image loading. See Production Limits and Errors.
allowImageResizing	boolean	true	Shows native resize handles for a selected image. It does not affect insertion or rendering.
onContentChange	(html: string) => void	Optional	Receives the current HTML after a content change.
onContentChangeJSON	(json: DocumentJSON) => void	Optional	Receives the current ProseMirror JSON after a content change.
onSelectionChange	(selection: Selection) => void	Optional	Receives engine document positions.
onActiveStateChange	(state: ReadonlyActiveState) => void	Optional	Receives marks, nodes, available commands, allowed marks, and insertable nodes for the current selection.
onHistoryStateChange	(state: HistoryState) => void	Optional	Receives undo and redo availability.
onFocus	() => void	Optional	Called when the native editor gains focus.
onBlur	() => void	Optional	Called when the native editor loses focus.
focusPreservingRefs	RichTextEditorFocusPreservingRefs	Optional	One native view ref or a readonly array of refs. Taps inside those views preserve editor focus, keyboard, and selection.
onLocalCommit	() => void	Optional	Application notification after a successful local mutation. It is not a transport trigger.
style	StyleProp	Optional	Style for the native editor view. It does not style document internals.
containerStyle	StyleProp	Optional	Style for the React wrapper around the native view and any inline toolbar.
theme	EditorTheme	Optional	Typed per-element document stylesheet plus toolbar chrome, usually created with EditorStyleSheet.create. See Styling and EditorTheme Reference.
addons	EditorAddons	Optional	Readonly array of addon descriptors and conditional false, null, or undefined entries. Supports mentions and optional code highlighting; duplicate capabilities are rejected. See Addons.
atoms	readonly AtomNodeDefinition[]	Optional	Custom React renderers for block atom types in the handle schema. See Custom Atom Nodes.
atomsInteractive	boolean	true	Enables atom controls independently of editable.
virtualizeAtoms	boolean	false	Uses the native scroll viewport to unmount offscreen React atom renderers.
atomViewport	AtomViewport	Optional	Explicit { y, height, overscan? } range in native atom-layout coordinates; overrides the native viewport. Overscan defaults to 200 points. See Custom Atom Nodes.
remoteSelections	readonly RemoteSelectionDecoration[]	Optional	Awareness decorations for other participants. The collaboration hook creates these for you.

Controlled-content rules

• value wins over valueJSON when both are supplied.
• A controlled JSON apply is an engine mutation, not a replacement of the handle. Do not use it as a second source of truth for a room handle; spread collaboration.editorBindings instead.
• valueJSONUpdateMode only affects controlled JSON applies. Ref setContent and setContentJson preserve undo history; clearContent resets it.
• A room handle in AwaitRemote is intentionally not rendered until an accepted room document is available. It never falls back to a local paragraph.
• Rebinding a mounted editor from one ready handle to another preserves the native view, focus, keyboard, and a clamped caret selection without showing a loading frame. Rebinding to an AwaitRemote room still shows loading and does not inherit focus.

Input value unions

Export	Values
RichTextEditorHeightBehavior	fixed, autoGrow
RichTextEditorToolbarPlacement	keyboard, inline
RichTextEditorValueJSONUpdateMode	replace, reset
RichTextEditorAutoCapitalize	none, sentences, words, characters
RichTextEditorKeyboardType	default, email-address, numeric, phone-pad, ascii-capable, numbers-and-punctuation, url, number-pad, name-phone-pad, decimal-pad, twitter, web-search, visible-password, ascii-capable-number-pad
RichTextEditorAndroidInputOptions	privateImeOptions?: string

RichTextEditorFocusPreservingRefs accepts one RichTextEditorFocusPreservingRef or a readonly array. Each ref must resolve to a native element with measureInWindow, such as a React Native View or Pressable. See Toolbar Setup for an example.

Ref API

Pass a React ref typed as RichTextEditorRef. Ref methods target the mounted editor and its current selection; they do not initialize or own a document session.

Method	Result	Behavior
focus(), blur()	void	Move native focus.
supportsExternalTextComposition()	boolean	Whether the mounted and bound native editor supports external text composition.
beginExternalTextComposition(options?)	Promise	Begin provisional text composition at the current text selection.
toggleMark(markType)	void	Toggle a schema mark, such as bold.
setLink(href), unsetLink()	void	Apply or remove the link mark on the current selection.
toggleBlockquote()	void	Toggle a blockquote wrapper.
toggleHeading(level)	void	Toggle heading level 1 through 6.
toggleList(listType)	void	Toggle a list whose schema name is supplied by the caller.
indentListItem(), outdentListItem()	void	Change the current list-item nesting.
insertNode(nodeType)	void	Insert a void node with its schema defaults, such as horizontal_rule or a custom atom.
insertImage(src, attrs?)	void	Insert the standard block image with optional alt, title, width, and height.
insertText(text)	void	Insert text at the current cursor.
insertContentHtml(html), insertContentJson(doc)	void	Insert an HTML or JSON fragment at the current selection.
setContent(html), setContentJson(doc)	void	Replace the complete document with an undoable boundary.
clearContent()	void	Authoritatively reset to the handle schema’s empty document, discard pending native input/composition, and clear history.
getContent(), getContentJson(), getTextContent()	string, DocumentJSON, string	Read the current ready document. A not-ready room returns empty values.
getCaretRect()	Promise<RichTextEditorCaretRect | null>	Get editor-local x, y, width, height, editorWidth, and editorHeight; null means native layout has no caret geometry yet.
undo(), redo()	void	Undo or redo one history group. Paste and cut each create a separate undo step. See Undo and redo.
canUndo(), canRedo()	boolean	Read the current ready history capability.

NativeEditorDocumentHandle policy can still reject an otherwise valid ref mutation, for example when readOnly is set. See Production Limits and Errors.

External composition updates are provisional and do not mutate the document until commit. The session can also end because of editor interaction, a document change, or native lifecycle. See External Text Composition for the complete contract.

Request and awareness contexts

LinkRequestContext

Field	Meaning
href?	Existing link target at the selection when the request was issued.
isActive	Whether link is active at that selection.
selection	Captured Selection in engine document positions.
setLink(href)	Applies or updates the link at the editor's current selection.
unsetLink()	Removes the link at the editor's current selection.

The package deliberately does not ship a URL modal. See Links and Images for the host-owned flow.

ImageRequestContext

Field	Meaning
selection	Captured Selection in engine document positions.
insertImage(src, attrs?)	Inserts the block image. attrs may contain alt, title, width, and height.

Base64 acceptance is creation-time policy on the handle, while imageLoadingPolicy bounds native fetching and decoding. They are separate controls.

RemoteSelectionDecoration

Field	Meaning
clientId	String identity of the remote participant.
anchor, head	Remote document positions.
color	Selection and caret color.
name?, avatarUrl?, isFocused?	Optional presence presentation.

Use the remoteSelections from useYjsCollaboration rather than recreating it from a separate JavaScript collaboration store.

Toolbar behavior

DEFAULT_EDITOR_TOOLBAR_ITEMS is: bold, italic, underline, strike, blockquote; a separator; bullet_list and ordered_list, indent and outdent, hard_break, horizontal_rule; a separator; undo and redo. It contains no default link or image button.

Link is disabled without a permitted link mark and onRequestLink. Image is disabled without an insertable image node and onRequestImage. For groups, each child's enabled state is calculated independently; an expand group reveals its action-resolvable children inline and a menu group presents them in a menu. See Toolbar Setup and EditorToolbar Reference.

Related pages

• Content and State
• Toolbar Setup
• Links and Images
• Collaboration
• External Text Composition
• Custom Atom Nodes
• Types and Events Reference