Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Activate your Pro license (once per machine)
npx koalaui-cli@latest login <key>

# Add this component (its dependencies come along)
npx koalaui-cli@latest add rich-text-editor

Usage#

Anatomy#

import {
  RichTextEditor,
  RichTextEditorToolbar,
  RichTextEditorButton,
  RichTextEditorSeparator,
  RichTextEditorAlignGroup,
  RichTextEditorContent,
  RichTextEditorBubbleMenu,
} from "@/components/ui/rich-text-editor"

<RichTextEditor>
  <RichTextEditorToolbar>
    <RichTextEditorButton />
    <RichTextEditorSeparator />
    <RichTextEditorAlignGroup />
  </RichTextEditorToolbar>
  <RichTextEditorContent />
  <RichTextEditorBubbleMenu>
    <RichTextEditorButton />
  </RichTextEditorBubbleMenu>
</RichTextEditor>

Placeholder#

An empty editor shows muted ghost text. Set it with the placeholder prop.

Image links#

People paste links to screenshots rather than upload them. With imageLinks, any paragraph, heading or code block that links to a .png, .jpg, .gif, .webp or .avif shows the picture right under it. It is a decoration, not content: the HTML you save keeps the link alone, and an expired link simply shows nothing.

A complete composer#

Everything together: a seeded document, the full toolbar, the on-selection bubble, a scrollable writing area, and a status bar that lives inside the editor surface: live word/character counts (tabular-nums, so they never reflow) and a save action with transient confirmation. The status bar is just a child that reads the editor via useRichTextEditor.

Selection bubble menu#

Drop in RichTextEditorBubbleMenu and a floating toolbar surfaces over the current selection. Double-click a word or drag across a phrase and it appears above it (Medium / Notion style). It pairs with the top toolbar or replaces it entirely. Its link control expands inline so the selection-driven bubble never dismisses while you type the URL.

Or go chromeless: omit the top toolbar and let the bubble be the only formatting UI.

Text alignment#

Alignment is opt-in. Pass alignment and paragraphs and headings can be set left, center, right or justified; the default toolbar gains an alignment group, with Tiptap's Mod-Shift-L/E/R/J shortcuts in its tooltips. Pass a list instead of true to offer only some of them. The alignment is written into the HTML as style="text-align: center;", so it survives a save and a reload. Left is the natural flow of a line, so choosing it clears the alignment rather than writing one. Without the prop nothing changes: an editor never keeps an alignment it can't show a control for.

In a toolbar or bubble of your own, place RichTextEditorAlignGroup where you want the controls (size="sm" in a bubble). It is a single-choice toggle group that joins the bar's arrow-key navigation, and it renders nothing while alignment is off.

Labels#

Every string the built-in controls speak or show (the toolbar names, the tooltips that double as aria-labels, and the link editor's field and buttons) comes from labels. Pass the keys you want to change; the rest keep their English defaults. The ghost text stays on placeholder.

Extending the editor#

The document model is open. starterKit reconfigures the built-in StarterKit key by key, over Koala's own setup: a key you set replaces that extension's options, and false drops the extension. Narrow the headings to the levels your HTML uses, keep typed URLs as text, or stop the editor appending an empty paragraph after a closing list (trailingNode: false), so a document saved elsewhere loads and saves back unchanged. extensions registers more Tiptap extensions after the built-in ones: a mark, a node, a plugin or, here, a keyboard shortcut that sends the reply. Their commands reach the live editor through useRichTextEditor. Both are read when the editor mounts, like the rest of its schema.

Density#

Like the rest of Koala, the editor honors density. compact tightens the writing area for dense app surfaces. The toolbar sits outside that axis: its 8px padding is what keeps the controls' 12px corners concentric inside the 20px frame, and a format bar that shrank with form density would get hard to hit, so the controls hold 32px either way. Set it per instance or once with a DensityProvider.

Read-only#

Pass editable={false} and omit the toolbar to render stored content as styled prose, useful for previews and feeds.

Custom toolbar#

With no children the toolbar renders the essential controls. For a custom set, pass RichTextEditorButtons and reach the live editor with the useRichTextEditor hook (pair it with Tiptap's useEditorState to reflect active formatting).

Prose scale#

Inside the editor, blocks render on a document scale tuned for reading: the heading steps mirror Tailwind's @tailwindcss/typography prose-sm proportions, scaled to the 14px body (no plugin dependency). Headings run text-3xl → text-sm in the strong foreground, while body copy stays the muted secondary color, so a document reads calm with only its headings and emphasis lifted. These sizes are fixed by the component. For the raw scale they draw from, see the Typography foundation.

API reference#

FAQ#