# Rich Text Editor

A Tiptap-powered WYSIWYG editor with a formatting toolbar.

- Category: Forms
- Page: https://wunderui.com/components/rich-text-editor
- Tier: Free

## Install

```bash
npx wunderui-cli add rich-text-editor
```

## Import

```tsx
import { RichTextEditor, RichTextEditorProps, RichTextEditorSkeleton } from "@/components/wunderui/rich-text-editor"
```

## Minimal usage

Then use it:

```tsx
import { useState } from "react"
import { Label } from "@/components/ui/label"
import { RichTextEditor } from "@/components/ui/rich-text-editor"

export function Notes() {
  const [html, setHtml] = useState("")

  return (
    <div className="flex flex-col gap-1">
      <Label id="notes-label" className="mb-1">
        Meeting notes
      </Label>
      <RichTextEditor aria-labelledby="notes-label" placeholder="Write a short note..." onChange={setHtml} />
      <p className="text-xs text-text-tertiary">{html}</p>
    </div>
  )
}
```

Expected result: You should see the label Meeting notes above a frame with a toolbar of six buttons and the grey placeholder. Type some text and press Bold: the button turns pressed and the HTML shows a strong tag.

## Usage

```tsx
import { RichTextEditor } from "@/components/ui/rich-text-editor"

export function Example() {
  return (
    <RichTextEditor aria-label="Meeting notes" placeholder="Write a short note..." />
  )
}
```

## When to use

### Use Rich Text Editor for

- Notes, descriptions and release notes where bold, lists and links make the text easier to scan
- A reply or a comment that people format before they send it
- Content that is stored as HTML and shown formatted somewhere else

### Use something else

- [Textarea](https://wunderui.com/components/textarea) for plain text over several lines, such as a message or feedback
- [Prompt Input](https://wunderui.com/components/prompt-input) for the message box of an AI chat, which is not a rich text editor
- [Input](https://wunderui.com/components/input) for one line of text, such as a title or a name

## Keyboard

Every toolbar button is its own tab stop, followed by the editing area. In the text the shortcuts are the ones of the editing engine, with Cmd instead of Ctrl on a Mac, and there is none for the link.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus through the toolbar buttons and into the editing area. Inside a list item that has an item before it, Tab indents the item and Shift+Tab outdents it; when the item cannot move, Tab leaves the editor. |
| `Enter` or `Space` | On a toolbar button: turns the format on or off. Link opens the browser's prompt for the address. |
| `Ctrl+B` or `Ctrl+I` or `Ctrl+U` | Toggles bold, italic or underline on the selected text, or for the text typed next. |
| `Ctrl+Shift+8` or `Ctrl+Shift+7` | Turns the paragraph into a bulleted or a numbered list, or back into a paragraph. |
| `Enter` | Starts a new paragraph, or a new list item inside a list. |
| `Shift+Enter` | Inserts a line break inside the same paragraph. |
| `Ctrl+Z` or `Ctrl+Shift+Z` | Undoes and redoes the last edit. |

## Behavior

What the editor does with the text, the toolbar and the loading, and what it leaves to the page.

- **Loading:** The editing engine is a separate chunk, so an app that never shows the editor never downloads it. A skeleton with the same frame shows until it loads, so nothing moves.
- **Content in and out:** The content is the HTML the editor starts with, and the change handler gets the whole document as HTML after every edit. Changing the content later does nothing; a new key loads other text.
- **Toolbar state:** Every button reads the selection and is pressed while the cursor is inside bold, italic or underlined text, a list or a link. A press keeps the focus in the text.
- **What it can write:** Paragraphs and line breaks, bold, italic, underline, bulleted and numbered lists, and links. Other common elements such as headings and quotes survive pasting, but there is no button for them.
- **Links:** The Link button asks for the address in the browser's prompt: an address sets the link, an empty answer removes it, Cancel leaves it. Clicking a link in the editor does not follow it.
- **Labelling:** The editing area is a multi-line textbox, and aria-label, aria-labelledby and aria-describedby reach it. A click on a Label does not move focus into it, because labels only do that for form controls.
- **Focus:** When the text has focus, the whole frame turns indigo with the 2 px ring, because the text itself has no outline. A toolbar button shows its own indigo border and ring.
- **Size:** The editing area is at least 128 px tall and grows with the text, so the page scrolls, not the editor. After a list the document ends with an empty paragraph, so you can keep typing.
- **No disabled, read-only or invalid state:** The Figma set draws disabled, read-only and invalid states, but the React editor does not take them yet. Render the saved HTML for read-only text, and colour the frame for an error.
- **Motion:** The toolbar buttons change fill and colour quickly on hover and press. Nothing moves or scales, and typing never animates.
- **Reduced motion:** With reduced motion the same colour change stays: it is a short fade, not movement.

## Anatomy

- `RichTextEditor`: A 16 px frame with a 1 px border around the toolbar and the editing area. It loads its engine (Tiptap) on first render, shows a skeleton until then and gets an indigo ring on focus.
- `RichTextEditorSkeleton`: The empty frame with the placeholder that shows until the editor has loaded, 38 px of toolbar and 128 px of text. Export it for your own loading state.
- `Toolbar`: A row of 28 px icon buttons in 6 px of padding with a 2 px gap, closed off from the text by a 1 px line. The buttons are Bold, Italic, Underline, Bulleted list, Numbered list and Link.
- `Toolbar button`: A 28 px icon button with an 8 px corner. It is a toggle, shown pressed while the cursor is in text with that format, and Link asks for the address in the browser's prompt.
- `Separator`: A 1 px line, 20 px high, between the text styles, the lists and the link.
- `Editing area`: The editable text: a multi-line textbox at least 128 px tall with 12 px padding that grows with its content. While empty it shows the placeholder, and you name it with an aria-label.

## Best practices

### When to use

- Use a Rich Text Editor for text that people format: a note, a project description, a reply, release notes. For plain text use a Textarea; for a message to an AI assistant use a Prompt Input.

### Do

- Name the editing area with aria-labelledby pointing to a visible Label, or an aria-label when there is no room. A label with htmlFor cannot reach it, because the area is not a form control.
- Store the HTML from the change handler and pass it back as the content when the person returns. The content is the starting text only, so use a new key to load other content.
- Sanitize the HTML on your server before you store it or show it to other people. The editor limits the tags it produces, but a server should never trust the browser.
- Say what is wrong next to the editor and keep the text. The editor has no invalid state of its own, so colour the frame with the error border and link the message with aria-describedby.
- Turn on slashMenu for longer documents such as notes and briefs: "/" opens a block menu at the caret (headings, lists, task, quote, divider, code). Keep it off for short replies, where the toolbar is enough.

### Don't

- Don't use it for text that must stay plain, such as a name, a title or a search term. The output is HTML, not plain text, and a one-line Input is easier to fill in.
- Don't use it as the composer of an AI chat. That is a Prompt Input: it sends on Enter, grows with the message and has attach and send buttons, not a formatting toolbar.
- Don't rely on a shortcut for the link. There is none: the toolbar button is the way to add or remove a link.

## API reference

### RichTextEditor

| Prop | Type | Default | Description |
|---|---|---|---|
| aria-describedby | string |  | The id of the element that describes the editing area, such as a helper line or an error message. |
| aria-label | string |  | The accessible name of the editing area when there is no visible label. |
| aria-labelledby | string |  | The id of the element that names the editing area, such as a visible `Label`. Use it instead of `htmlFor`, which does not reach a text box that is not a form control. |
| className | string |  | Extra classes on the frame, for example `border-error` to mark a problem or a width. |
| content | string |  | The HTML the editor starts with, for example `<p>Ship <strong>before Friday</strong>.</p>`. It is read once: later changes to the prop do not replace what was typed, so use a new `key` to load other content. |
| id | string |  | The `id` of the editing area, for `aria-labelledby` and `aria-describedby` of other elements to point at. |
| onChange | (html: string) => void |  | Called with the whole document as an HTML string after every edit. Store it, and pass it back as `content` when the person returns. |
| placeholder | string |  | The grey text shown while the editor is empty. Defaults to `Write something...`. It is not a label. |
| slashMenu | boolean \| SlashItem[] |  | Typing "/" at the start of a line or after a space opens a block menu at the caret: arrow keys pick, Enter or Tab inserts, Escape closes, typing filters. `true` shows the default blocks (headings, lists, task, quote, divider, code); pass y… |

### RichTextEditorSkeleton

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string |  | Extra classes on the frame of the skeleton, the same as on the editor. |
| placeholder | string |  | The text shown in the skeleton, so it matches the placeholder of the editor that replaces it. |

## Examples

### Content: empty, text, inline styles, lists and a link

```tsx
import { RichTextEditor } from "@/components/ui/rich-text-editor"

export function Example() {
  // While the editor is empty it shows the placeholder.
  return (
    <RichTextEditor aria-label="Meeting notes" placeholder="Write a short note..." />
  )
}
```

### States: empty, filled and focus

```tsx
import { RichTextEditor } from "@/components/ui/rich-text-editor"

export function Example() {
  return (
    <RichTextEditor aria-label="Meeting notes" placeholder="Write a short note..." />
  )
}
```

### Label and helper: a visible label, a helper line or only a name

```tsx
import { Label } from "@/components/ui/label"
import { RichTextEditor } from "@/components/ui/rich-text-editor"

export function Example() {
  // The editing area is a div, so a label cannot point at it with htmlFor: name it with aria-labelledby.
  return (
    <div className="flex flex-col gap-1">
      <Label id="description-label" className="mb-1">
        Project description
      </Label>
      <RichTextEditor
        aria-labelledby="description-label"
        placeholder="Describe the project..."
      />
    </div>
  )
}
```

### Output: the HTML that onChange returns

```tsx
import { useState } from "react"
import { RichTextEditor } from "@/components/ui/rich-text-editor"

const START = "<p>Ship <strong>before Friday</strong>.</p>"

export function Example() {
  const [html, setHtml] = useState(START)

  return (
    <div className="flex flex-col gap-3">
      <RichTextEditor aria-label="Note" content={START} onChange={setHtml} />
      <pre className="rounded-xl border border-border bg-bg-page p-3 font-mono text-xs break-all whitespace-pre-wrap">{html}</pre>
    </div>
  )
}
```

### Block menu: type / for headings, lists, tasks and more

```tsx
import { RichTextEditor } from "@wunderui/react"

export function Example() {
  // Type / at the start of a line or after a space: arrow keys pick a block, Enter inserts it, Escape closes the menu.
  return (
    <RichTextEditor
      aria-label="Meeting notes"
      slashMenu
      content="<h2>Product sync</h2><p>Agenda for the launch review. Type / on a new line to add a block.</p>"
    />
  )
}

```

## In context

### Comment reply: a reply box under a message

Reply stays disabled until there is text. The reply is shown as formatted text and Cancel clears the box; try a list by typing a dash and a space.

```tsx
import { useState } from "react"
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { Button } from "@/components/ui/button"
import { RichTextEditor } from "@/components/ui/rich-text-editor"

// The editor returns HTML made of a fixed set of tags. Sanitize it on your server before you store or show it.
const isEmpty = (html: string) => html.replace(/<[^>]*>/g, "").trim() === ""

export function Example() {
  const [html, setHtml] = useState("")
  const [draft, setDraft] = useState(0)
  const [replies, setReplies] = useState<string[]>([])

  return (
    <div className="flex flex-col gap-4">
      <div className="flex gap-3">
        <Avatar>
          <AvatarFallback>DO</AvatarFallback>
        </Avatar>
        <div>
          <p className="text-sm font-medium">Daniel Okafor</p>
          <p className="text-sm text-text-secondary">Can we move the roadmap review to Thursday?</p>
        </div>
      </div>
      {replies.map((reply, index) => (
        <div key={index} className="flex gap-3">
          <Avatar>
            <AvatarFallback>NL</AvatarFallback>
          </Avatar>
          <div>
            <p className="text-sm font-medium">Nora Lindgren</p>
            <div
              className="text-sm text-foreground [&_a]:text-text-link [&_a]:underline [&_ol]:list-decimal [&_ol]:pl-5 [&_ul]:list-disc [&_ul]:pl-5"
              dangerouslySetInnerHTML={{ __html: reply }}
            />
          </div>
        </div>
      ))}
      <RichTextEditor key={draft} aria-label="Reply" placeholder="Write a reply..." onChange={setHtml} />
      <div className="flex justify-end gap-2">
        <Button
          variant="plain"
          onClick={() => {
            setHtml("")
            setDraft((value) => value + 1)
          }}
        >
          Cancel
        </Button>
        <Button
          variant="gradient"
          disabled={isEmpty(html)}
          onClick={() => {
            setReplies((list) => [...list, html])
            setHtml("")
            setDraft((value) => value + 1)
          }}
        >
          Reply
        </Button>
      </div>
    </div>
  )
}
```

### Project brief: a description that must not be empty

Save with an empty description to see the error: the frame turns red, the helper line becomes the message and focus stays where it was. Typing clears it.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"
import { RichTextEditor } from "@/components/ui/rich-text-editor"

const isEmpty = (html: string) => html.replace(/<[^>]*>/g, "").trim() === ""

export function Example() {
  const [html, setHtml] = useState("")
  const [error, setError] = useState(false)
  const [saved, setSaved] = useState(false)

  return (
    <form
      className="flex flex-col gap-4"
      noValidate
      onSubmit={(event) => {
        event.preventDefault()
        setError(isEmpty(html))
        setSaved(!isEmpty(html))
      }}
    >
      <div className="flex flex-col gap-1">
        <Label htmlFor="brief-title" className="mb-1">
          Title
        </Label>
        <Input id="brief-title" defaultValue="Q3 roadmap review" />
      </div>
      <div className="flex flex-col gap-1">
        <Label id="brief-label" className="mb-1">
          Description
        </Label>
        <RichTextEditor
          aria-labelledby="brief-label"
          aria-describedby="brief-help"
          placeholder="Describe the goal and the milestones..."
          className={error ? "border-error" : undefined}
          onChange={(next) => {
            setHtml(next)
            setError(false)
            setSaved(false)
          }}
        />
        <p id="brief-help" role={error ? "alert" : undefined} className={error ? "text-xs text-text-error" : "text-xs text-text-tertiary"}>
          {error ? "Add a description before you save." : "Shown on the project page."}
        </p>
      </div>
      <div className="flex items-center justify-end gap-2">
        <p aria-live="polite" className="mr-auto text-sm text-text-secondary">
          {saved ? "Brief saved." : ""}
        </p>
        <Button type="submit" variant="gradient">
          Save brief
        </Button>
      </div>
    </form>
  )
}
```

### Release notes: read the saved text, edit it, save it

The saved HTML is shown as text. Edit opens the editor with it as the starting content, and Save keeps what was typed.

```tsx
import { useState } from "react"
import { Button } from "@/components/ui/button"
import { RichTextEditor } from "@/components/ui/rich-text-editor"

export function Example() {
  const [saved, setSaved] = useState("<p>Version 2.4 adds <strong>keyboard shortcuts</strong> to the editor.</p><ul><li>Faster lists</li><li>Clearer focus</li></ul>")
  const [html, setHtml] = useState(saved)
  const [editing, setEditing] = useState(false)

  return editing ? (
    <div className="flex flex-col gap-3">
      <RichTextEditor aria-label="Release notes" content={saved} onChange={setHtml} />
      <div className="flex justify-end gap-2">
        <Button variant="plain" onClick={() => setEditing(false)}>
          Cancel
        </Button>
        <Button
          variant="gradient"
          onClick={() => {
            setSaved(html)
            setEditing(false)
          }}
        >
          Save notes
        </Button>
      </div>
    </div>
  ) : (
    <div className="flex flex-col gap-3">
      <div
        className="text-sm text-foreground [&_a]:text-text-link [&_a]:underline [&_ol]:list-decimal [&_ol]:pl-5 [&_ul]:list-disc [&_ul]:pl-5"
        dangerouslySetInnerHTML={{ __html: saved }}
      />
      <Button
        variant="plain"
        className="self-start"
        onClick={() => {
          setHtml(saved)
          setEditing(true)
        }}
      >
        Edit notes
      </Button>
    </div>
  )
}
```

## For AI agents

`get_component("rich-text-editor")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
