RichText

A rich text editor with a formatting toolbar, markdown shortcuts, links, task lists, a slash menu, find and replace and image upload.

RichText installs separately; it is not part of @elements/ui. The import comes with that install, and the template is used as shown.

Example
<RichText value={post.body} label="Body" placeholder="Write something..." />

<!-- a short field: a few tools, a limit, submitted with the form -->
<RichText name="bio" tools={["bold", "italic", "link"]} limit={280} count rows={3} />

Parts

Part	What it is
RichText	The frame: toolbar, editable content, count line, hidden form control and slash menu.
.rich-text-toolbar	role="toolbar" with one tab stop; arrow keys move between tools.
.rich-text-tool	A toolbar button: a .toggle with aria-pressed for marks and blocks.
.rich-text-prose	The contenteditable, role="textbox" aria-multiline.
.rich-text-footer	The character count, in a line that is always reserved.
.rich-text-slash	The slash menu: a listbox at the caret, highlighted with aria-activedescendant.
.rich-text-find	The find and replace panel (Mod+F): find and replace fields, the match count, previous, next, replace, replace all, and match case, whole words and regex toggles. Floats over the top end of the text.
.rich-text-upload	An image upload in progress, in the text: file name, percent, cancel and a progress bar. The image replaces it when upload resolves.
.find-and-replace-result	A find match in the text; the current one also has .find-and-replace-result-current.

Attributes

Attribute	Type	Default	Description
value	string (two-way)	""	The document, in format. Bind it to state; the editor writes every change back, and writing it from outside replaces the document. Empty is "".
format	"html" | "json" | "text"	"html"	What value holds: HTML, the document as JSON in a string (editor.getJSON()), or plain text (paragraphs separated by a blank line).
placeholder	string	""	Shown in the empty editor, and set as aria-placeholder.
label	string	""	Accessible name of the text box (aria-label). Or pass aria-labelledby in attrs.
tools	RichTextTool[]	DEFAULT_TOOLS	The toolbar's controls in order: undo, redo, block, bold, italic, underline, strike, code, highlight, link, bulletList, orderedList, taskList, list (the three lists in one menu), blockquote, codeBlock, horizontalRule, align, clear, image (shown with upload), find, and | for a separator.
toolbar	boolean	true	Shows the toolbar. Shortcuts and markdown input work without it.
stickyToolbar	boolean	false	The toolbar sticks to the top of the scrolling page while the editor is in view.
headingLevels	(1 | 2 | 3 | 4 | 5 | 6)[]	[1, 2, 3, 4]	Heading levels the document allows, the text style menu offers and the slash menu lists. Changing it rebuilds the editor around the same document.
slashMenu	boolean	true	Typing / opens a menu of blocks at the caret.
slashOptions	RichTextSlashOptions	{}	Suggestion options for the menu: the trigger (char, allowSpaces, allowToIncludeChar, allowedPrefixes, startOfLine, minQueryLength, allow, shouldShow, shouldResetDismissed, findSuggestionMatch, pluginKey), its decoration (decorationTag, decorationClass, decorationContent, decorationEmptyClass), the items (items, initialItems, debounce, command, render with mount) and placement (placement, offset, flip, container, floating, dismissOnOutsideClick).
parseOptions	ParseOptions	{}	Parse options for HTML content, such as { preserveWhitespace: "full" }.
coreExtensionOptions	CoreExtensionOptions	{}	Options for the built-ins: clipboardTextSerializer.blockSeparator joins copied blocks.
rows	number	6	Minimum height of the content, in lines.
maxRows	number	0	Height where the content stops growing and scrolls. 0 grows without limit.
limit	number	0	Maximum characters. Typing and pasting stop at the limit; the count line shows n / limit. A new limit applies at once.
count	boolean	false	Shows the character and word count. On by itself when limit is set.
name	string	""	Submits value with a form under this name.
required	boolean	false	With name: an empty editor blocks the form's submit and takes focus.
disabled	boolean	false	Not editable, not focusable, dimmed; the toolbar is off and the form control is not submitted.
readonly	boolean	false	Not editable, still selectable and submitted; the toolbar is off.
invalid	boolean	false	Danger border and aria-invalid="true".
autofocus	boolean | "start" | "end" | "all"	false	Focuses the editor when it mounts, with the caret at the start, the end (true) or everything selected.
dir	"" | "ltr" | "rtl" | "auto"	""	Text direction of the content and the toolbar's arrow keys. Changes apply live.
extensions	Extension[]	[]	Your own extensions (Extension.create): key bindings, input rules, editor plugins, commands, and nodes and marks for the schema. Their keys run after the built-in formatting keys.
exclude	RichTextBuiltin[]	[]	Built-ins to leave out, as turning off a StarterKit extension does: marks (bold, italic, underline, strike, code, highlight, link, superscript, subscript), blocks (heading, blockquote, bulletList, orderedList, taskList, codeBlock, horizontalRule, hardBreak, image) and helpers (undoRedo, dropcursor, gapcursor, trailingNode). Their tools, slash items, shortcuts and markdown rules go, and pasted content drops them. An extension may define its own node or mark under a left-out name. Changing it rebuilds the editor.
inputRules	boolean	true	Markdown shortcuts as you type (# heading, - list, **bold**). false types them literally.
pasteRules	boolean	true	Markdown and links in pasted text become formatting.
enableContentCheck	boolean	false	Checks content against the schema: content with a node or mark the editor does not know fires onContentError and is refused instead of being dropped.
emitContentError	boolean	false	Keeps invalid content parsing as usual but still fires onContentError.
highlights	RichTextHighlight[]	HIGHLIGHTS	The highlight popover's swatches: { name, color } with any CSS color. The swatch's data-rich-text-swatch is the name in lower case.
autoOpenLink	boolean	true	Opens the link popover when the caret enters a link, with focus left in the text; moving out closes it. false keeps it to Mod + K and the link tool.
find	boolean	true	Find and replace on Mod + F and the find tool. false leaves Mod + F to the browser.
findOpen	boolean	false	Two-way: the find panel is open. Set it to open or close the panel; Mod + F and Escape write it back.
linkOpen	boolean	false	Two-way: the link popover is open. Set it to open the popover with its field focused.
upload	((file: File, onProgress: (percent: number) => void, signal: AbortSignal) => Promise<string>) | null	null	Uploads an image and resolves to its URL. Turns on the image tool, Mod + Shift + I, and image drop and paste. Cancel aborts the signal.
imageAccept	string	"image/*"	File types the image chooser, drop and paste accept, as in an input's accept.
imageMaxSize	number	0	Largest image in bytes. 0 is no limit.
imageLimit	number	1	Images per upload. Above 1 the chooser takes several files.
class	string	""	Extra classes on the frame.
attrs	Record<string, string | number | boolean | undefined>	{}	Attributes for the text box: id, aria-labelledby, aria-describedby, data-testid.
onValueChange	(value: string) => void	() => {}	Called when the editor changes the document. Not called for writes to value from outside.
onCreate	(editor: Editor) => void	() => {}	Called once the Editor is ready, for commands (editor.chain().focus().toggleBold().run()) and events (editor.on) the attributes do not cover.
onSelectionUpdate	(editor: Editor) => void	() => {}	The selection moved; read editor.state.selection or editor.isActive().
onFocus	(e: FocusEvent) => void	() => {}	The text box gained focus.
onBlur	(e: FocusEvent) => void	() => {}	The text box lost focus.
onUploadError	(error: Error) => void	() => {}	A file was refused (type, size or count) or its upload failed.
onUploadSuccess	(url: string) => void	() => {}	An upload finished and its image is in the text.
onContentError	(error: Error) => void	() => {}	Content the schema cannot hold, with enableContentCheck or emitContentError.
onFindOpenChange	(open: boolean) => void	() => {}	The find panel opened or closed on its own: Mod + F, the find tool, Escape or close.
onLinkOpenChange	(open: boolean) => void	() => {}	The link popover opened or closed on its own.
onSetLink	(href: string) => void	() => {}	After the link popover applies a link, with the href written.
onHighlightApplied	(highlight: RichTextHighlight) => void	() => {}	After the highlight popover applies a swatch, with its name and color.

Slots

Slot	Content
toolbar	Extra controls after the built-in tools. Give them class="toggle is-sm rich-text-tool" to join the toolbar's look and arrow-key focus.

Keyboard

Keys	Action
Mod + B / I / U	Bold, italic, underline. Mod is Cmd on a Mac, Ctrl elsewhere.
Mod + Shift + S	Strikethrough.
Mod + E	Inline code.
Mod + Shift + H	Highlight.
Mod + . / Mod + ,	Superscript, subscript. Each replaces the other.
Mod + K	Opens the link popover for the selection.
Mod + F	Opens find and replace; in the panel, selects the find field.
Enter / Shift + Enter	In the find field: next and previous match.
Arrow Down / Up, Mod + Shift + F / D	In the find panel: next and previous match.
Enter (replace field)	Replaces the current match and moves to the next.
Escape (find panel)	Closes find, clears the marks and returns to the text.
Mod + Shift + I	Chooses an image to upload (with upload).
Mod + Alt + 0 to 6	Paragraph, or heading 1 to 6 (levels in headingLevels).
Mod + Shift + 7 / 8 / 9	Numbered list, bullet list, to-do list.
Mod + Shift + B	Quote.
Mod + Alt + C	Code block.
Mod + Shift + L / E / R / J	Align left, center, right, justify.
Mod + Z / Mod + Shift + Z	Undo, redo (Mod + Y also redoes).
Shift + Enter	Line break inside a paragraph.
Tab / Shift + Tab	In a list: indent and outdent the item. Elsewhere: leaves the editor.
Alt + F10	From the text: moves focus to the toolbar.
Arrow Left / Right, Home, End	In the toolbar: move between tools.
Escape	In the toolbar: back to the text. In the slash menu or a popover: closes it. Inside a Dialog these stay the editor's, so the Dialog stays open.
/	Opens the slash menu; type to filter, Arrow Up / Down to move, Enter or Tab to insert.
# ## ### - 1. [] > ``` ---	Markdown shortcuts at the start of a line: headings, lists, to-do, quote, code block, divider.
**text** *text* ~~text~~ `text` ==text==	Markdown marks: bold, italic, strike, code, highlight.
" ... -> (c) 1/2	Typography as you type: smart quotes, ellipsis, arrows, symbols and fractions.

Data attributes

Attribute	Values	On	Description
data-focused	present	.rich-text	While the text box has focus.
data-empty	present	.rich-text	While the document is empty.
data-ready	present	.rich-text	Once the editor has mounted.
data-disabled	present	.rich-text
data-readonly	present	.rich-text
data-invalid	present	.rich-text
data-state	"on" | "off"	.rich-text-tool	on while the mark, block or alignment is active at the selection.
data-highlighted	present	.rich-text-slash-item
data-loading	present while items() is pending (aria-busy too)	.rich-text-slash
data-limit-reached	present	.rich-text-footer
data-rich-text-find-option	"match-case" | "whole-words" | "use-regex"	.rich-text-find button	Which match option a toggle sets; data-state on or off.

Accessibility

• The content is a contenteditable with role="textbox" and aria-multiline="true", named by label or aria-labelledby, with aria-placeholder, aria-readonly, aria-disabled, aria-invalid and aria-required as they apply.
• The toolbar is role="toolbar" with aria-controls pointing at the text box and one tab stop; arrow keys move between tools (WAI-ARIA toolbar pattern). Alt + F10 reaches it from the text and Escape returns.
• Mark, block and alignment tools are toggle buttons with aria-pressed and aria-keyshortcuts; a tool that cannot apply at the selection is aria-disabled but stays focusable.
• Pressing a tool with the mouse does not move focus, so the selection stays in the text.
• The slash menu is a listbox; the text box gets aria-expanded, aria-controls and aria-activedescendant so a screen reader follows the highlight while typing continues.
• The count line is aria-live="polite" and is referenced by aria-describedby when limit is set.
• The find panel is role="dialog" named "Search and replace"; its match count is aria-live="polite" and its option toggles carry aria-pressed. Read-only text stays focusable so it can be searched.
• The link popover that opens when the caret enters a link leaves focus in the text, so typing and screen reader reading go on.
• An upload placeholder is a group named for the file with a progressbar and a named cancel button.

See also

• CodeEditor (opens in a new tab): A code editor with highlighting, line numbers, folding, completion, search, multiple cursors and diagnostics.