EditorTheme Reference

EditorTheme Reference

The 2.x EditorTheme is a typed map of native document element styles plus a toolbar configuration. Use EditorStyleSheet.create() for exact property checking and runtime validation, or pass an EditorTheme to the editor/viewer. See Styling for examples.

Element styles

All elements are optional. Every element except toolbar accepts EditorStyleProp<T>: an object, false, null, undefined, or a nested readonly array of these values. Later objects override earlier properties; this is a shallow property merge. taskCheckbox.checked also accepts style arrays. The whole theme is a named map, not an array.

Element	Type	Purpose
content	EditorSurfaceStyle	Native surface background, padding, and borders.
text	EditorTypographyStyle	Base text typography.
paragraph, h1–h6, blockquote, codeBlock	EditorTextStyle	Block typography, alignment, and box appearance.
bulletList, orderedList, taskList	EditorListStyle	List containers, plus indent and baseIndentMultiplier.
listItem, taskItem	EditorTextStyle	Item typography and box appearance.
listMarker	EditorListMarkerStyle	color, scale, gap, ordered.
taskCheckbox	EditorTaskCheckboxStyle	Borders, backgroundColor, checkColor, size, gap, checked.
horizontalRule	EditorHorizontalRuleStyle	Borders, margins, backgroundColor, height.
image	EditorImageStyle	Box appearance and resizeMode.
link, inlineCode, bold, italic, underline, strike	EditorInlineStyle	Typography and backgroundColor.
mention	EditorMentionStyle	Inline typography/background plus borders and padding.
placeholder	EditorTypographyStyle	Placeholder typography.
rules	readonly EditorStyleRule[]	Ancestry-scoped style overrides layered on top of the elements above.
toolbar	EditorToolbarTheme	Toolbar configuration object; no style arrays.

The style keys are semantic element names. They do not declare schema nodes or enable document features.

Shared property groups

Type	Optional fields
EditorTypographyStyle	fontFamily, fontSize, fontWeight, fontStyle, color, lineHeight, letterSpacing, textDecorationLine, textDecorationColor, textDecorationStyle.
EditorBorderStyle	borderWidth, borderColor, borderStyle, borderTopWidth, borderRightWidth, borderBottomWidth, borderLeftWidth, corresponding four edge colors, borderRadius, and four corner radii.
EditorPaddingStyle	padding, paddingHorizontal, paddingVertical, paddingTop, paddingRight, paddingBottom, paddingLeft.
EditorMarginStyle	margin, marginHorizontal, marginVertical, marginTop, marginRight, marginBottom, marginLeft.
EditorSurfaceStyle	Borders, padding, backgroundColor.
EditorBoxStyle	Surface fields plus margins.
EditorTextStyle	Typography, box fields, textAlign.
EditorInlineStyle	Typography, backgroundColor; no margin or padding.
EditorMentionStyle	Inline fields plus borders and padding; no margins.
EditorCheckboxAppearance	Borders, backgroundColor, checkColor; also used by taskCheckbox.checked.

The corner keys are borderTopLeftRadius, borderTopRightRadius, borderBottomRightRadius, and borderBottomLeftRadius. After array merging, specific edges override axis/all-edge shorthands; specific corners override borderRadius.

Property	Accepted values
fontWeight	normal, bold, string 100–900, or numeric 100–900 in steps of 100.
fontStyle	normal, italic.
textAlign	auto, left, right, center, justify.
textDecorationLine	none, underline, line-through, underline line-through.
textDecorationStyle	solid, double, dotted, dashed.
borderStyle	solid, dashed, dotted.
image.resizeMode	contain, cover, stretch; native default is contain.

Colors must be strings recognized by React Native's color processing, such as #2563eb, rgba(37, 99, 235, 0.2), or transparent. Dynamic color objects and numeric colors are not accepted. Numbers must be finite. fontSize, lineHeight, checkbox size, and marker scale must be positive. Margins and letterSpacing may be negative; other numeric fields must be nonnegative. Undefined property values are omitted. Unknown elements/properties, invalid enums/colors/numbers, and cyclic arrays throw TypeError rather than being silently ignored.

These are editor styles, not the complete React Native style API. Layout dimensions, flexbox, percentages, transforms, shadows, and registered numeric style IDs are unsupported here. Font families must be installed in the native app. Justification uses native layout on iOS and Android API 26+; API 24–25 renders normal paragraph alignment without inter-word justification.

Contextual rules by ancestry

The flat element styles above apply uniformly wherever an element appears. theme.rules layers additional styles onto an element only when it sits inside a specific ancestor chain, for example a codeBlock nested in a blockquote, or a listMarker inside a particular listItem.

const theme = EditorStyleSheet.create({
    codeBlock: { fontFamily: 'monospace' },
    rules: [
        { path: ['blockquote', 'codeBlock'], style: { fontFamily: 'Courier-Bold' } },
        { path: ['listItem', 'listMarker'], style: { color: '#2563eb' } },
    ],
});

Each entry is { path, style }:

• path is a nonempty, ordered, readonly array of element names ending in the element the rule targets. The last entry fixes the accepted style shape, typed the same as that element's flat entry — a listMarker rule's style is EditorListMarkerStyle, a codeBlock rule's is EditorTextStyle, and so on.
• style follows the same property validation and array-merge rules as a flat element style. A rule's style cannot itself contain rules.

Matching

A rule matches an element when path is a contiguous suffix of that element's full ancestor chain, root to self. ['blockquote', 'paragraph'] matches a paragraph whose immediate parent is a blockquote. It does not match a paragraph reached through blockquote > bulletList > listItem > paragraph, because bulletList/listItem break the contiguous run — write the full intervening chain (['blockquote', 'bulletList', 'listItem', 'paragraph']) to reach through nested containers, or shorten path to ['listItem', 'paragraph'] to match any paragraph directly under a list item regardless of what contains the list.

Rules are resolved after the flat element style, in rules array order: a later matching rule overrides properties set by an earlier matching rule or by the flat element style, using the same shallow-merge precedence as style arrays. Inline marks (bold, italic, link, inlineCode, underline, strike) can also be rule targets; their ancestor chain is the surrounding block stack, so a rule can style, for example, inline code differently only inside a blockquote or a list item.

rules are resolved natively on both iOS and Android, for the editor and the viewer, so contextual styling stays consistent between editing and read-only rendering.

Lists and task checkboxes

indent and baseIndentMultiplier live independently on bulletList, orderedList, and taskList. Use item marginBottom for item gaps and list marginBottom for spacing after a list. listMarker.gap separates list markers from content; taskCheckbox.gap controls the checkbox gap.

listMarker.ordered accepts:

Field	Type	Default
schemes	Nonempty readonly EditorOrderedListNumberingScheme[]	decimal, lowerAlpha, lowerRoman.
suffix	. or )	..

Schemes are decimal, lowerAlpha, upperAlpha, lowerRoman, and upperRoman. They cycle by visual nesting depth, including unordered and task-list ancestors.

taskCheckbox.checked overrides checkbox appearance when checked; its fields are borders, backgroundColor, and checkColor. Set size and gap on taskCheckbox itself.

Mentions

theme.mention sets base chip presentation. The mentions addon can supply theme.node overrides and suggestion UI styling. A persisted per-node mentionTheme takes precedence over the addon defaults for supplied fields. Mention padding, borders, per-edge colors/widths, and corner radii render in both editor and viewer.

Export	Optional fields
EditorMentionTheme	node, suggestions.
EditorMentionNodeTheme	EditorMentionStyle fields; deprecated textColor remains accepted for persisted themes. Prefer color.
EditorMentionSuggestionsTheme	backgroundColor, borderColor, borderWidth, borderRadius, shadowColor, option.
EditorMentionSuggestionOptionTheme	textColor, secondaryTextColor, backgroundColor, borderColor, borderWidth, borderRadius, fontWeight, highlightedBackgroundColor, highlightedTextColor.

EditorMentionStyle and addon theme.node accept padding, paddingHorizontal, paddingVertical, paddingTop, paddingRight, paddingBottom, and paddingLeft. Values are finite, nonnegative layout units; 0 removes padding on the selected edges. Specific edges override axis shorthands, which override padding. After normalization, each supplied edge overrides the corresponding edge from the lower-priority theme. Unspecified edges retain their inherited value or native default.

Native mention padding	Horizontal	Vertical
iOS	6	4
Android	4	2

Set explicit padding for matching insets across platforms. Border widths add to the chip insets separately. theme.mention supports style arrays; addon theme.node is a single object.

Suggestion container fields apply to the JavaScript EditorToolbar; native keyboard toolbars style rows only. option.textColor remains the suggestion-row API even though node text uses color. See Mentions.

Toolbar

EditorToolbarTheme keeps a dedicated configuration shape:

• appearance: custom (default) or native.
• height, backgroundColor, borderColor, borderWidth, borderRadius, marginTop.
• showTopBorder, keyboardOffset, horizontalInset, separatorColor.
• buttonIconSize, buttonColor, buttonBackgroundColor, buttonActiveColor, buttonDisabledColor, buttonActiveBackgroundColor, buttonDisabledBackgroundColor, buttonBorderRadius.

appearance selects native keyboard toolbar chrome, not toolbar placement. It does not turn the standalone React toolbar into a native accessory. keyboardOffset and horizontalInset concern keyboard placement; marginTop and showTopBorder concern React inline/standalone presentation.

Native keyboard toolbar	Geometry and defaults
iOS, custom	Offset 0, horizontal inset 0, bar radius 0, border width 0.5, button radius 8.
Android, custom	Offset 0, horizontal inset 0, bar radius 0, border width 1, button radius 6.
iOS, native	Offset 6, horizontal inset 10; normally forces a one-physical-pixel border. Earlier iOS uses a supplied bar radius or 20, and button radius or 10. With Swift 6.2+ on iOS 26+, the bar instead uses capsule corners with maximum radius 24; nonempty mention buttons enable transparent mention chrome with border width 0.
Android, native	Offset 8, horizontal inset 0; forces bar stroke 0, bar radius 32, and button radius 20.

Placement offsets remain caller-controlled. Native chrome can override custom paint and geometry; use custom for caller-controlled borders/radii.

The standalone React EditorToolbar defaults to height 40, white background, separator/border #E5E5EA, idle button #666666, active #007AFF, disabled #C7C7CC, transparent idle fill, active fill rgba(0, 122, 255, 0.12), and button radius 6. Without a disabled fill, disabled buttons retain their active or idle fill. showTopBorder resolves from its prop, then theme, then true; RichTextEditor inline placement defaults it to false.

Every toolbar leaf or group may set buttonStyle: EditorToolbarButtonStyle to override icon size, idle/active/disabled colors and fills, and border radius for that button. See EditorToolbar Reference.

Updating a 1.x theme

Previous token	Current element style
Root backgroundColor, borderRadius, contentInsets	content.backgroundColor, content.borderRadius, content.padding*.
headings.h1–headings.h6	h1–h6.
spacingAfter	Corresponding block/list marginBottom.
blockquote.text, codeBlock.text	Typography directly on blockquote / codeBlock.
blockquote.indent, markerGap	Express the quote's box with padding and borders.
list	Separate bulletList, orderedList, taskList, listItem, taskItem, listMarker, and taskCheckbox.
links.underline	link.textDecorationLine: 'underline'.
horizontalRule.color, thickness, verticalMargin	backgroundColor, height, marginVertical.
placeholderColor	placeholder.color.

The old token map is not a supported alias for the new TypeScript API. Geometry expressed with the new box model may need visual adjustment on each platform.