Types and Events Reference

Types and Events Reference

This is the lookup page for package-root shared state, custom atom, collaboration, and addon exports. The component-specific props and events are on RichTextEditor Reference, RichTextViewer Reference, and EditorToolbar Reference.

Document state and rendering

Export	Fields / meaning
DocumentJSON	Open record. Its valid shape is determined by the handle schema.
Selection	type: text, node, or all; optional anchor/head/pos document positions and optional anchorScalar/headScalar/posScalar native scalar positions.
ActiveState	marks, markAttrs, nodes, commands boolean/name records plus allowedMarks and insertableNodes arrays.
ReadonlyActiveState	Recursively immutable ActiveState supplied by atomic render snapshots and editor callbacks.
HistoryState	canUndo and canRedo booleans.
EditorUpdate	renderElements; optional renderBlocks and renderPatch; selection, activeState, historyState; optional documentVersion.
RenderElement	Prepared native render element. Void blocks may carry optional atomId identity in addition to node type, attrs, and document position.
RenderBlocksPatch	startIndex, deleteCount, renderBlocks. It replaces a contiguous range of prepared render blocks.
NativeEditorAtomicRenderSnapshot	Immutable union containing either renderBlocks with renderPatch null, or renderBlocks null with a RenderBlocksPatch. It also contains selection, activeState, historyState, documentVersion, stateRevision, scalarLength, and documentIsEmpty.
CollaborationPeer	clientId string, isLocal boolean, state record or null.

Render blocks are native implementation payloads carried by the root-exported snapshot and patch types. They are not a React component tree or a second document format. Use DocumentJSON for persistence and editor/viewer content.

Custom atoms

Export	Contract
AtomComponent / AtomComponentProps	Generic React component receiving readonly attrs, selected, readOnly, isViewer, nodeType, interactive, updatePending, updateError, updateAttrs, setActive, and optional editor actions.
AtomAttrsUpdate	A partial attrs object, a function of current readonly attrs, or an ordered readonly array of either.
AtomEditorActions	Asynchronous select, delete, focusBefore, and focusAfter methods, supplied by the editor host.
InferAtomAttrs	Infers attribute values from an attribute-spec map.
AtomNodeConfig / AtomNodeDefinition	Definition input and compiled block-atom result from defineAtomNode().
SerializedEditorAtoms / serializeEditorAtoms()	Native-boundary registration payload containing node types and estimated heights.
AtomUpdateAttrsErrorCode	not-applicable, stale-revision, not-ready, or engine-error.
AtomUpdateAttrsError	Typed updateAttrs rejection with one AtomUpdateAttrsErrorCode.
AtomViewport	y and height, plus optional overscan, in atom-layout coordinates; overscan defaults to 200 points.
AtomInstance	Mounted identity, nodeType, attrs, and docPos derived from render blocks.
collectAtomInstances()	Collects registered custom void blocks from prepared render blocks.
applyRenderPatch()	Applies one RenderBlocksPatch to previous blocks.
atomSelected()	Tests whether a Selection covers an atom document position.
DEFAULT_ATOM_CHIP_HEIGHT	Fallback chip height, 32.
NATIVE_VOID_BLOCK_TYPES	Built-in native void-block names skipped unless explicitly registered.

Most applications use only defineAtomNode, withAtomsSchema, AtomComponentProps, AtomUpdateAttrsError, and RichTextEditor.atoms / RichTextViewer.atoms. See Custom Atom Nodes for the complete lifecycle and persistence contract.

External text composition

These types are exported from the package root:

Export	Contract
ExternalTextCompositionOptions	Optional onEnd callback for the terminal session event.
ExternalTextCompositionSession	Provisional update(text) plus terminal commit(finalText) and cancel() methods.
ExternalTextCompositionEndEvent	Terminal outcome, cause, resulting text, and optional typed error.
ExternalTextCompositionEndCause	consumer, interaction, documentChange, or lifecycle.

See External Text Composition for availability, lifecycle, and document behavior.

Local awareness

createNativeEditorLocalAwarenessSelection(anchor, head) creates the opaque, runtime-verified NativeEditorLocalAwarenessSelection used by NativeEditorLocalAwarenessIntent.

NativeEditorLocalAwarenessIntent field	Meaning
state	Required application presence record.
focused	Required local focus state.
selection omitted	Retain the sticky cursor Rust already owns. Use for focus-only or state-only updates.
selection: null	Publish presence without a cursor.
selection: factory result	Publish validated anchor/head positions for the current document.

Do not construct a selection object literal. The factory's provenance is checked before native publication.

Collaboration transport

NativeCollaborationTransportConfig has url, connect, and optional protocolAdapter. Set transport to null to detach a controller from a room.

NativeCollaborationProtocolAdapter is an optional RN-owned, attempt-scoped prelude around the native-owned WebSocket:

Field	Contract
protocols	Required ordered WebSocket subprotocol tokens.
timeoutMillis	Optional maximum pending-adapter time.
terminalCloseCodes	Optional close codes that park Rust transport rather than permit automatic retry.
onOpen(context)	Required. Returns or resolves a protocol result.
onMessage(context, frame)	Required. Returns or resolves a protocol result for a native-delivered prelude frame.

NativeCollaborationProtocolAdapterContext has attemptId, generation, and negotiatedProtocol or null. NativeCollaborationProtocolFrame is text with string data or binary with Uint8Array data. NativeCollaborationProtocolAdapterAction is continue, ready, or reject. NativeCollaborationProtocolAdapterResult contains action and optional readonly frames.

Native blocks Yjs traffic until an adapter callback returns ready. Callback results and credentials are used only for the current physical attempt; native/Rust own the WebSocket, Yjs traffic, reconnect eligibility, and retry timing.

Transport events

NativeCollaborationTransportEvent is the root-exported discriminated event union. NativeCollaborationProtocolAdapterEvent is its root-exported kind: 'protocolAdapter' branch; inspect kind for the state and error shapes rather than depending on source-module event interface names:

kind	Fields
state	editorId, eventSequence, generation or null, state: NativeEditorState, peers: NativeEditorPeerInfo[], diagnostics.
error	editorId, eventSequence, generation or null, error: NativeEditorErrorBase.
protocolAdapter	editorId, eventSequence, generation, attemptId, eventId, negotiatedProtocol, phase open or message, and frame for message.

NativeCollaborationTransportDiagnostics contains wakeReason, transportState, nextDeadlineMillis or null, remoteCommitApplied, peersChanged, renewedLocal, and expiredPeerCount. NativeEditorPeerInfo contains clientId, clock, isLocal, state or null, and cursor anchor/head or null.

Yjs collaboration helpers

Export	Contract
YjsTransportStatus	idle, disconnected, connecting, handshaking, synchronized, incompatible, destroyed. It projects the native transport state.
LocalAwarenessUser	userId, name, color, optional avatarUrl and extra.
LocalAwarenessState	user required; optional Selection and focused.
YjsCollaborationState	documentId, status, isConnected, documentJson or null, documentRevision or null, optional lastError.
YjsCollaborationOptions	documentId, handle, transport; optional localAwareness, onPeersChange, onStateChange, onError.
YjsCollaborationController	state, peers, documentHandle; connect, disconnect, reconnect, destroy, updateLocalAwareness, handleSelectionChange, handleFocusChange.
YjsCollaborationEditorBindings	documentHandle, documentRevision, remoteSelections, onFocus, onBlur. Spread this into RichTextEditor.
UseYjsCollaborationResult	state, peers, isConnected; connect, disconnect, reconnect, updateLocalAwareness, editorBindings.
createYjsCollaborationController(options)	Imperative controller factory. Destroy it before its handle.
useYjsCollaboration(options)	React hook that owns controller subscription and cleanup.

The hook intentionally does not return a controlled valueJSON or a JavaScript selection binding. Native adapters and Rust update the one shared handle directly.

Mentions and addons

Export	Contract
MENTION_NODE_NAME	The literal node name mention.
mentionNodeSpec()	Standard void inline mention node with a label default and pass-through attrs.
withMentionsSchema(schema)	Adds that node unless a node named mention already exists.
buildMentionFragmentJson(attrs, descriptor?, options?)	Builds a mention JSON fragment using the active document-root name; MentionFragmentOptions.trailingSpace optionally appends an unmarked space.
EditorAddon	MentionsAddon or CodeHighlightingAddon capability descriptor.
EditorAddonEntry / EditorAddons	A descriptor, false, null, or undefined; a readonly flat array of these entries.
createMentionsAddon(options?) / MentionsAddon	Creates an immutable mentions descriptor.
MentionsAddonOptions	MentionsAddonConfig plus viewer prefix and onPress.
MentionPressEvent	docPos, label, and attrs from a viewer mention press.
CodeHighlightingAddon / CodeHighlightingAddonOptions	Highlighting descriptor and its provider/theme options. Create it with the separately installed scoped package.
MentionsAddonConfig	trigger?, suggestions?, theme?, resolveSelectionAttrs?, resolveTheme?, onQueryChange?, onSelect?.
MentionSuggestion	key, title, optional subtitle, label, attrs.
MentionQueryChangeEvent	query, trigger, anchor/head range, isActive, optional documentVersion.
MentionSelectionAttrsEvent	trigger, suggestion, attrs, anchor/head range, optional documentVersion.
MentionThemeResolveEvent	Alias of MentionSelectionAttrsEvent.
MentionSelectEvent	trigger, suggestion, attrs, optional documentVersion.
EditorAddonEvent	Native event union: mentionsQueryChange, mentionsSelectRequest, or mentionsSelect.

The editor forwards onQueryChange and onSelect. It calls resolveSelectionAttrs immediately before insertion and validates/persists the value from resolveTheme as mentionTheme. Create a new createMentionsAddon({ suggestions, ...options }) descriptor from normal React state when a query needs a new result set; see Mentions.

Stylesheets

EditorStyleSheet.create(styles) validates and returns the supplied typed element map. Compose styles with nested arrays on each element; normalization resolves them before native rendering. EditorTheme accepts the map plus toolbar configuration. These are plain style objects, not React Native registered numeric IDs. Mention-suggestion UI configuration belongs to the mentions addon.

The root exports EditorStyleProp, EditorStyleMap, and the supported property groups: EditorTypographyStyle, EditorBorderStyle, EditorPaddingStyle, EditorMarginStyle, EditorSurfaceStyle, EditorBoxStyle, EditorInlineStyle, EditorImageStyle, EditorListStyle, EditorListMarkerStyle, EditorCheckboxAppearance, EditorTaskCheckboxStyle, EditorHorizontalRuleStyle, and EditorMentionStyle. See EditorTheme Reference for each element's supported fields and inheritance.

Where each root export lives

Export family	Reference page
RichTextEditor and its props/ref/callback types	RichTextEditor Reference
RichTextViewer and its props/event/addon types	RichTextViewer Reference
EditorToolbar, items, groups, icons, default values	EditorToolbar Reference
EditorTheme and all exported theme tokens	EditorTheme Reference
Document handle, hook, schemas, policies, limits, errors	Document API Reference
Custom atom definitions, components, updates, and render helpers	Custom Atom Nodes
Shared document state, external text composition, awareness, Yjs controller, transport, mentions	This page

Related pages

• Collaboration
• External Text Composition
• Mentions
• Content and State
• Production Limits and Errors