RichTextEditor is a form field for formatted text: bold, italic, headings, lists and links. People format with the toolbar, the usual shortcuts (Mod-B, Mod-I) or Markdown as they type (## , - , 1. , > ). The value is HTML. It is built on TipTap, which loads only when an editor renders.
RichTextEditor has its own entry point, @once-ui-system/core/richtext, so apps that do not use it do not load it.
It needs TipTap 3, which is an optional peer dependency of @once-ui-system/core. Install it in the app that renders the editor:
Without these packages the editor renders a notice that names the missing dependency, and logs the install command to the console.
The editor mounts on the client only. On the server, and until TipTap has loaded, it renders an empty frame of the same height, so the page does not shift.
The value is the document as HTML. defaultValue sets the starting document for an uncontrolled editor. For a controlled one, pass value and onValueChange, which runs on every change. An empty document is "", not "<p></p>", so a required check can test for an empty string.
The editor does not sanitize HTML. Run the saved HTML through your sanitizer before you show it anywhere else.
tools sets the toolbar's buttons, in the order given. The default is bold, italic, heading, bulleted list, numbered list, link, undo and redo. underline, strike and code are also available. The heading button toggles a level 2 heading, and ### typed at the start of a line makes a level 3 heading.
tools={false} hides the toolbar. The keyboard shortcuts and Markdown shortcuts still work.
The link button opens an address field under the toolbar. An address without a scheme gets https://. Addresses with mailto:, tel:, a leading / or # are kept as typed, and any other scheme, javascript: included, is refused. On a link, the same button removes it.
minHeight is the writing area's least height, as a CSS length, and defaults to "8rem". With maxHeight, the writing area scrolls once the document is taller.
Inside a Field, leave out label. The Field's label names the editor, and its hint and error describe it. While error is set, the editor draws its invalid look. Give the editor an id, or the Field gives it one.
readOnly shows the document without the toolbar, and the text can still be selected and copied. disabled also hides the toolbar and draws the field dimmed. Neither can be edited.
labels translates the toolbar's name and each button's name. Fields you leave out stay in English.
- The writing area has role="textbox" and aria-multiline="true". Name it with label, aria-label or aria-labelledby, or put it inside a Field. A <label> cannot name an editable region, so with label or a Field the editor points at the label with aria-labelledby.
- aria-describedby, aria-invalid and aria-required are passed to the writing area. A Field sets them for you.
- readOnly and disabled set aria-readonly and aria-disabled.
- The toolbar has role="toolbar" and is named by labels.toolbar ("Formatting" by default). Each button is named by its label, which is also its title. Format buttons report their state with aria-pressed, and the link button reports the address field with aria-expanded.
- In the address field, Enter applies the link and Escape closes the field.
- autoFocus moves focus into the editor when it mounts, with the cursor at the end. Use it only where the editor is the reason the page or dialog opened.
RichTextEditor also takes the layout and style props of Column (margin, fillWidth, className, style and the rest), except children, onChange, defaultValue, id, aria-label, minHeight and maxHeight, which it defines itself.
"bold" | "italic" | "underline" | "strike" | "code" | "heading" | "bulletList" | "orderedList" | "link" | "undo" | "redo"