Rich Text Editor

Usage

RichTextEditor is for prose a person writes and a product stores: a release note, a comment, a bio, a description. It is a Tiptap editor underneath, so the document model, the schema, the undo history and the input rules are ProseMirror's rather than ours.

The value is a Tiptap JSON document, not an HTML string. onValueChange hands you that document first and the derived views — html, text, isEmpty, characterCount, wordCount — beside it, so storing structured content never means parsing your own markup back out.

Tab always leaves the editor. The list extensions bind Tab to indent, which turns a list into a keyboard trap; that binding is removed here and indentation moves to Ctrl+] / Ctrl+[ (Cmd on macOS) and to the toolbar's Indent and Outdent buttons.

Every button is icon-only, so each one carries a tooltip naming it and, where the command has one, its keybinding. React Aria opens it on keyboard focus as well as hover, which is what keeps it from being a pointer-only affordance.

Every example on this page carries the same toolbar, so the only thing that changes between them is the one behaviour each is about. It reads left to right as history, marks, blocks, lists and links, indentation, then the two clears. Action buttons carry a persistent circular chip and toggle buttons stay bare until they are on, because an action has no on state and would otherwise sit there looking like a toggle that is permanently off. Indent and Outdent are the exception: they are structural edits belonging with the list buttons beside them, so they stay plain.

Anatomy

Import the RichTextEditor component and access all parts using dot notation. It ships from @blakeui/pro-react/editor rather than the package root: it is the only component built on Tiptap, and Tiptap is an optional peer, so keeping it out of the root barrel is what lets every other component install without ProseMirror.

import {RichTextEditor} from "@blakeui/pro-react/editor";

<RichTextEditor>
  <RichTextEditor.Shell>
    <RichTextEditor.Toolbar>
      <RichTextEditor.ToolbarGroup>
        <RichTextEditor.ToggleButton command="bold" />
        <RichTextEditor.ActionButton action="undo" />
        <RichTextEditor.LinkPopover>
          <RichTextEditor.LinkPopover.Trigger />
          <RichTextEditor.LinkPopover.Content>
            <RichTextEditor.LinkPopover.Input />
            <RichTextEditor.LinkPopover.Actions>
              <RichTextEditor.LinkPopover.UnsetButton />
              <RichTextEditor.LinkPopover.ApplyButton />
            </RichTextEditor.LinkPopover.Actions>
          </RichTextEditor.LinkPopover.Content>
        </RichTextEditor.LinkPopover>
      </RichTextEditor.ToolbarGroup>
      <RichTextEditor.ToolbarSeparator />
    </RichTextEditor.Toolbar>
    <RichTextEditor.Content />
    <RichTextEditor.Footer>
      <RichTextEditor.FooterText />
      <RichTextEditor.CharacterCount />
    </RichTextEditor.Footer>
  </RichTextEditor.Shell>
</RichTextEditor>;

Content is the only part whose position is fixed relative to nothing — put the toolbar above it or below it, keep the footer or drop it. Nothing React-owned may be rendered inside Content: ProseMirror reconciles that subtree itself.

LinkPopover goes wherever its trigger belongs in the toolbar. It portals its own panel out to document.body, so nesting it inside a ToolbarGroup costs nothing and keeps the trigger in the toolbar's roving order where it belongs.

Character Count

Controlled

Custom Composition

Disabled And Read Only

Extensible Commands

Placeholder

CSS Classes

The root here is .rich-text-editor. Three stylesheets meet on these elements, and the order between them is most of the styling story.

@blakeui/styles dresses .toolbar, .toggle-button and .button, because the toolbar and its buttons are those free components — this page does not reimplement a toolbar, it takes React Aria's. Both layers live in @layer components and the Pro layer is imported second, so a rule of equal specificity wins on source order and nothing below needs doubling up. Two free rules are fought by name: .toolbar is a w-fit single-row grid, which would run past the shell rather than wrap, and .toggle-button is a 40px text pill where this toolbar wants a 32px square.

ProseMirror owns everything inside .rich-text-editor__prosemirror. Those nodes are not React elements and can never carry a class from a prop, so the document's type ramp is written as element selectors under the root — the one place in the component where that is right rather than lazy.

The shell is seamless. There is no rule under the toolbar and none above the footer; the shell's own stroke is the only border, and the three rows are told apart by padding plus the toolbar's vertical group separators. Nothing replaces those rules — not a lighter one, not a background step, not a shadow — because a seam that is only almost invisible reads worse than either a real division or none. Verified by rasterising each row's composited background through a canvas: toolbar, content and footer come out byte-identical in both themes, at 1.00:1.

The third stylesheet in play is React Aria's, once the link popover is open. That panel is portaled to document.body, so it is not a descendant of the root at run time: it inherits no custom property declared on .rich-text-editor, and an @container query written on it would resolve against <body>. Everything it needs is declared on its own class.

Base Classes

• .rich-text-editor — The root. Declares every custom property below and stacks the shell and the live region as a flex column. Carries data-slot="rich-text-editor".
• .rich-text-editor__shell — The painted box. The fill is --field-background, so an editable surface reads as a field rather than as a card that happens to hold text. The stroke is not a field token: --field-border resolves to transparent in both themes, because the house field is filled and shadowed rather than stroked, so a border drawn from it measured a 1.00:1 boundary — no edge at all. It takes --border instead, the settled bordered-flat stroke for a container surface. overflow: clip, so the three rows meet the corner cleanly. It is the only border in the component: see the seamless note below.

Element Classes

• .rich-text-editor__toolbar — The role="toolbar" row. display: flex with flex-wrap: wrap, replacing the free .toolbar's single-row grid: nineteen controls have to wrap on a narrow container, not overflow it. Measured, it wraps to 2 rows at 1280 and 768 and 3 rows at 375, and never overflows.
• .rich-text-editor__toolbar-group — A layout box for buttons that belong together. Deliberately not role="group" — an unnamed group announces as a group with no name, which is noise rather than structure. The semantic division between runs is the separator.
• .rich-text-editor__toolbar-separator — The rule between two runs. The free Separator, which reads its orientation from the context the free Toolbar publishes, so it comes out upright inside a horizontal toolbar without being told.
• .rich-text-editor__toolbar-button — Every button in the toolbar, toggle and action alike. A square, because the glyphs are square and a text-button pill wastes a third of a narrow toolbar.
• .rich-text-editor__toolbar-button--action — The persistent chip on an ActionButton. Circular rather than the toggle's rounded rectangle, because a chip sharing that radius reads as a stuck toggle. Applied by the component from the command table, not by the call site — indent and outdent are marked plain there, since they are structural edits belonging with the list buttons rather than document-wide actions.
• .rich-text-editor__content — The scroll box. Carries the minimum height, so an empty editor is still a target worth clicking.
• .rich-text-editor__prosemirror — The contenteditable itself. It is the one class here applied through editorProps.attributes rather than a prop, because ProseMirror owns the element. outline: none — the focus ring goes on the shell instead, since ringing an element that fills the middle row would draw a rectangle inside the box. The placeholder inside it draws in --muted, not --field-placeholder: that token is theme-invariant and measures 3.67:1 on the dark field, under AA for text somebody is meant to read.
• .rich-text-editor__footer — The strip under the content. justify-content: space-between, so a leading slot and the count sit at opposite ends.
• .rich-text-editor__footer-text — The footer's leading slot. Takes the count's own type scale and muted ink, so the two ends read as one row.
• .rich-text-editor__character-count — The budget readout, and the element aria-describedby points at when maxLength is set.
• .rich-text-editor__tooltip — A toolbar button's tooltip. Portaled, like the link panel. The surface, corner, elevation and both motion curves come from .tooltip in @blakeui/styles and are not re-authored here; only the layout is, because that rule ships break-all, which would split a keybinding mid-symbol.
• .rich-text-editor__tooltip-key — The keybinding inside it, muted against the label because the label is the answer and the shortcut is the footnote.
• .rich-text-editor__link-popover — The floating link panel. Portaled, so it declares its own width and padding; the fill, elevation, corner and both halves of the reduced-motion opt-out come from .popover in @blakeui/styles and are not re-authored here.
• .rich-text-editor__link-input — The URL field's TextField wrapper, stacking the label over the input.
• .rich-text-editor__link-actions — The row the Apply and Remove buttons sit in.
• .rich-text-editor__announcement — The polite live region. Clipped rather than hidden, because display: none and visibility: hidden both take a live region out of the accessibility tree and stop it announcing at all.

States

• [data-disabled="true"] on the root — dims the shell and sets cursor: not-allowed. The editable region loses its tab stop with it, so the control has no tab stops left once its buttons are disabled too.
• [data-readonly="true"] on the root — stops every command but keeps the region focusable and selectable, because read-only text still has to be reachable to be read and copied.
• [data-selected="true"] on a toolbar button — React Aria's, and it rides alongside the real aria-pressed the ToggleButton sets. Never colour alone: the fill changes, the ink changes, and the pressed state reaches assistive tech as an attribute.
• [data-over-limit="true"] on the count — the budget is exceeded. --danger is a fill token and fails as small text on the dark page, so this paints a soft pill (--danger-soft behind --danger-soft-foreground) rather than recolouring the text to the fill. The wording changes with it and the live region announces the crossing, so the state never rests on colour.
• aria-expanded on the link trigger — React Aria's, from DialogTrigger, alongside an aria-controls that appears only while the panel is open. aria-haspopup="dialog" is written by this component: React Aria sets that attribute for menu and listbox only, on the reasoning that screen readers often announce any value as a menu.
• :focus on the region — the ring lands on .rich-text-editor__shell via :has().

CSS Variables

All declared on .rich-text-editor, so overriding one on the root retunes the whole component, including the parts ProseMirror renders.

• --rich-text-editor-content-min-height — The editable region's floor. 144px.
• --rich-text-editor-content-padding — The document's inset. 12px.
• --rich-text-editor-block-gap — The gap between two top-level blocks. 12px, and the one number that sets the document's rhythm.
• --rich-text-editor-control-size — A toolbar button, on both axes. 32px, which clears a 24px target with room to spare.
• --rich-text-editor-radius — The shell's corner. var(--radius-2xl).

Motion

There is no motion in this component, and that is deliberate rather than a gap. Everything below .rich-text-editor__prosemirror is reconciled by ProseMirror, which replaces nodes React never sees; a motion component mounted in there would be animating a subtree pulled out from under it. Keeping the animation in CSS on the chrome makes that impossible by construction rather than by convention.

The press affordance is the settled asymmetric timing: the press-in snaps (transition-duration: 0s) to scale: 0.92, and only the release eases back over 120ms on var(--ease-out). A symmetric press lags under the finger. It rides the standalone scale property rather than transform, which keeps it clear of the Tailwind transform variable chain the free button base sets up — and the transform: none that zeroes the free base's own press sits in a separate rule, because Lightning CSS folds a transform and a scale sharing one block into a single transform, and a folded transform is a property the reduced-motion opt-out below cannot reach.

The action chip is paint, not movement: a persistent --default fill and a circular radius, sharing the same hover, press and reduced-motion rules as every other toolbar button.

Neither the tooltip's motion nor the link popover's is authored here. Popover.Content composes .popover from @blakeui/styles, and Tooltip.Content composes .tooltip from the same place — both own their own curves, and both motion-reduce: variants already expand to the two halves of the opt-out. Overlay motion is fixed by a package version bump, never by a rule in a Pro component. Worth knowing about the tooltip's: its opt-out is animate-none, which removes the fade along with the movement, where this component's own rule keeps the fade. That is the free package's call, not this one's.

Everything else transitions colour only — the button fill and ink, the shell's border, the count — which under the settled rule needs no opt-out at all: there is no movement in it to remove. The reduced-motion opt-out therefore covers exactly one declaration, the press scale, and is dual: the explicit [data-reduce-motion="true"] hook and @media (prefers-reduced-motion: reduce), the media half scoped :not(…) so the two never double-apply. Gentler, never zero — the button still lights up on press, it just arrives in one frame.

API Reference

RichTextEditor

The root. Owns the Tiptap instance and publishes it to the parts, and deliberately does not subscribe to it — a root that re-rendered per transaction would re-render the whole subtree on every keystroke. Also accepts every native <div> attribute.

RichTextEditor.Shell

The painted box holding the toolbar, the content and the footer, and the element the focus ring lands on. Also accepts every native <div> attribute.

RichTextEditor.Toolbar

The button row. Also accepts every prop the @blakeui/react Toolbar takes.

RichTextEditor.ToolbarGroup

A layout box for buttons that belong together. Also accepts every native <div> attribute.

RichTextEditor.ToolbarSeparator

The rule between two runs of buttons. Renders the @blakeui/react Separator, so it also accepts that component's props, and it reads its orientation from the toolbar rather than being told.

RichTextEditor.ToggleButton

A mark or node that turns on and off. Renders the @blakeui/react ToggleButton, so it also accepts that component's props.

RichTextEditor.ActionButton

A one-shot command. Renders the @blakeui/react Button — deliberately not a toggle, since none of these has an on state, and an aria-pressed on undo would be announcing a state that does not exist.

RichTextEditor.LinkPopover

The link editor. Renders the @blakeui/react Popover, which is React Aria's DialogTrigger + Popover + Dialog — so the focus scope, Escape-to-close and focus-restore-to-trigger are the library's, and there is no second positioning library anywhere in the component. Its panel is portaled to document.body.

The document selection survives the popover. Focus moving into the URL field takes the DOM selection with it, but ProseMirror does not read the DOM back into state while it is blurred, so state.selection is untouched and Apply lands on exactly the range that was selected. What is lost is only the visual highlight; the fix for that is Tiptap's Selection extension, which needs both a new dependency and its own stylesheet — without the CSS it clears the native highlight and draws nothing, which is strictly worse — so it is deliberately left out.

Parts

RichTextEditor.Content

The ProseMirror surface, and the accessible control. Also accepts every native <div> attribute.

RichTextEditor.Footer

The strip under the content — where the count sits, and where a submit control would go. Also accepts every native <div> attribute.

RichTextEditor.CharacterCount

The budget readout. Subscribes to the counts alone, so it re-renders on a keystroke while the rest of the toolbar does not. Also accepts every native <p> attribute except id, which is fixed because the editable region's aria-describedby points at it.

RichTextEditor.FooterText

The footer's leading slot — a label, a status line, a hint. A real part rather than a bare paragraph at the call site, so it picks up the count's own type scale and muted ink and the two ends of the footer read as one row. Also accepts every native <p> attribute.

useRichTextEditor

Reads the live Tiptap Editor from the nearest RichTextEditor. null until the instance exists — it is created in an effect, not during render, so the first client render on a server-rendered page has no editor yet.

It does not subscribe to anything: reading editor.state from it gives a value that never updates. Use it to run commands, and reach for useRichTextEditorState to render from state.

useRichTextEditorState

Subscribes to a slice of editor state.