Text editor

01Preview

A real editor: select text and use the toolbar or keyboard shortcuts. The HTML it stores updates below. Change the controls to try toolbar subsets and states.

const [notes, setNotes] = useState(savedHtml)

<Field label="Lesson notes" hint="Students see these notes under the video.">
  <RichTextEditor
    value={notes}
    onChange={setNotes}
    placeholder="Write the key ideas of this lesson…"
  />
</Field>

<h2>Photosynthesis</h2><p>Plants turn <strong>light</strong>, water and carbon dioxide into glucose and oxygen.</p><ul><li><p>Happens in the chloroplasts</p></li><li><p>Needs chlorophyll</p></li></ul>

02Installation

1. Add the packages

pnpm add @nuton/ui @nuton/tokens @remixicon/react

npm install @nuton/ui @nuton/tokens @remixicon/react

yarn add @nuton/ui @nuton/tokens @remixicon/react

Peer dependencies: react and react-dom 18 or later. TipTap (@tiptap/react, @tiptap/starter-kit and three extensions, pinned to 3.31.4) installs with @nuton/ui; you don't add it yourself. Apps that never import RichTextEditor don't bundle it. @remixicon/react supplies the item icons (D1).

2. Load tokens and component styles once

// app/layout.tsx (or your app's entry file)
import '@nuton/tokens/tokens.css' // --nu-* design tokens
import '@nuton/ui/styles.css'     // component styles (uses the tokens)

No provider is needed. In Next.js, the editor renders on the client only (TipTap's immediatelyRender: false), so server-rendered pages hydrate cleanly.

03Usage

import { Field, RichTextEditor } from '@nuton/ui'

export function LessonNotes({ saved }: { saved: string }) {
  const [notes, setNotes] = useState(saved)
  return (
    <Field label="Lesson notes" hint="Students see these notes under the lesson video.">
      <RichTextEditor value={notes} onChange={setNotes} placeholder="Write the key ideas of this lesson…" />
    </Field>
  )
}

• Put the editor in a Field. The label, hint, error, required and disabled reach the content and the toolbar.
• The value is HTML. An empty editor reports ''. Pass name to submit it with a form.
• Show only the tools the task needs with tools, for example ['marks', 'lists'] for feedback.
• Sanitize stored HTML on the server before showing it to other people, and render it inside an element with the nu-rich-text class so it gets the same styles.
• Translate every string with labels outside English.

// Sanitize on the server (for example with DOMPurify), then:
<div className="nu-rich-text" dangerouslySetInnerHTML={{ __html: sanitizedHtml }} />

04Variants and sizes

There's one size. Figma's toolbar variants are subsets of the same items, and each item's Figma Type follows from its props.

Item types

<TextEditorToolbar>
  {/* Text: visible text and a caret, in a menu trigger */}
  <DropdownMenu>
    <DropdownMenuTrigger asChild>
      <TextEditorToolbarButton label="Text style">{block}</TextEditorToolbarButton>
    </DropdownMenuTrigger>
    {/* Paragraph, Heading 1, Heading 2, Quote */}
  </DropdownMenu>
  {/* Dropdown: icon and caret */}
  <DropdownMenu>
    <DropdownMenuTrigger asChild>
      <TextEditorToolbarButton icon={<RiFontSize />} caret label={`Text size, ${size}`} />
    </DropdownMenuTrigger>
    {/* Small, Medium, Large */}
  </DropdownMenu>
  <TextEditorToolbarSeparator />
  {/* Icon: toggles with pressed */}
  <TextEditorToolbarButton icon={<RiBold />} label="Bold" pressed={bold} onClick={toggleBold} />
  <TextEditorToolbarButton icon={<RiItalic />} label="Italic" pressed={italic} onClick={toggleItalic} />
  <TextEditorToolbarButton icon={<RiUnderline />} label="Underline" pressed={underline} onClick={toggleUnderline} />
  <TextEditorToolbarButton icon={<RiStrikethrough />} label="Strikethrough" pressed={strike} onClick={toggleStrike} />
  <DropdownMenu>
    <DropdownMenuTrigger asChild>
      <TextEditorToolbarButton icon={<RiAlignLeft />} caret label="Align left" />
    </DropdownMenuTrigger>
    {/* Align left, center, right */}
  </DropdownMenu>
  <TextEditorToolbarSeparator />
  {/* Color: swatch and caret */}
  <DropdownMenu>
    <DropdownMenuTrigger asChild>
      <TextEditorToolbarButton swatch={color} label={`Text colour, ${name(color)}`} />
    </DropdownMenuTrigger>
    {/* one named item per TEXT_EDITOR_COLORS entry */}
  </DropdownMenu>
</TextEditorToolbar>

Toolbar variants

Figma's Variant property shows four item sets. They aren't a prop: compose the items you need. The playground's variant control shows each one.

Sizes

Toolbar and item sizes follow Figma's geometry. Figma has no editing area, so the frame and content reuse Text Area (5:1282) styling (pending a decision). Figma shows a single-row toolbar; code lets it wrap so it reflows at 320px (WCAG 1.4.10).

Colours

TEXT_EDITOR_COLORS lists Figma's ten swatch colours, each the Foundation <hue>/500. The swatch is decoration: always name the colour in the control's label or menu item.

import { TEXT_EDITOR_COLORS, TextEditorSwatch } from '@nuton/ui'

{TEXT_EDITOR_COLORS.map((color) => (
  <figure key={color}>
    <TextEditorSwatch color={color} />
    <figcaption>{color}</figcaption>
  </figure>
))}

Orange, green, yellow, sky, pink and teal are below 3:1 against white, as Figma specifies (pending a decision). The swatch is aria-hidden, so the colour name carries the meaning (WCAG 1.4.1).

05States and interactions

Item states

Frame states

Figma has no frame, so these follow Text Area (pending a decision). Disabling the editor disables every toolbar button too.

06Composition examples

Assignment brief form

A required editor in a form. Submit it empty: the error is linked to the content and focus moves there. The name prop sends the HTML with the form.

const editorRef = useRef<Editor | null>(null)

function submit(e) {
  e.preventDefault()
  if (editorRef.current?.isEmpty) {
    setError('Describe the assignment before publishing.')
    editorRef.current.commands.focus()
    return
  }
  publish(new FormData(e.currentTarget).get('brief'))
}

<form onSubmit={submit} noValidate>
  <Field label="Assignment brief" required hint="Explain the task, the deadline and how it's marked." error={error}>
    <RichTextEditor
      name="brief"
      tools={['style', 'marks', 'lists', 'link']}
      placeholder="What should students do?"
      onEditorReady={(editor) => { editorRef.current = editor }}
    />
  </Field>
  <Button size="sm" type="submit">Publish assignment</Button>
</form>

Building your own editor

For a different tool set (mentions, comments) build on the shell parts. Any editable element can replace TextEditorContent. Spread useTextEditorContentProps() onto the engine's root so it gets the Field's label, hint, error and state. A contenteditable can't be the target of <label for>, so the name comes through aria-labelledby. Add role="textbox" and aria-multiline="true" if the engine doesn't. Here a plain contenteditable stands in for the engine.

function EngineRoot() {
  const a11y = useTextEditorContentProps()
  return (
    <div
      {...a11y}
      role="textbox"
      aria-multiline="true"
      contentEditable
      suppressContentEditableWarning
      tabIndex={0}
      className="nu-text-editor__content"
    >
      Cells are the basic unit of life…
    </div>
  )
}

<Field label="Lesson summary" hint="A plain contenteditable stands in for the engine's editable root.">
  <TextEditor toolbar={<FormattingToolbar />}>
    <EngineRoot />
  </TextEditor>
</Field>

With TipTap, read each toggle's pressed from editor.isActive() (via useEditorState) and run the command in onClick, as RichTextEditor does in its source.

Colour menu

A colour item opens a menu with one named option per colour. The item's label names the current colour.

<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <TextEditorToolbarButton swatch={color} label={`Text colour, ${name(color)}`} />
  </DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuRadioGroup value={color} onValueChange={setColor}>
      {TEXT_EDITOR_COLORS.map((c) => (
        <DropdownMenuRadioItem key={c} value={c} leading={<TextEditorSwatch color={c} />}>
          {name(c)}
        </DropdownMenuRadioItem>
      ))}
    </DropdownMenuRadioGroup>
  </DropdownMenuContent>
</DropdownMenu>

07API reference

RichTextEditor props

Also exported: RICH_TEXT_EDITOR_LABELS, RICH_TEXT_EDITOR_TOOLS, normalizeLinkHref(input) (the link dialog's check: allows http, https and mailto, completes bare domains and email addresses, rejects everything else) and richTextColorValue(color), the CSS value stored for a text colour.

TextEditor props

TextEditorContent props

TextEditorToolbar props

TextEditorToolbarButton props

The Figma Type (text, dropdown, icon, color) is derived from these props and exposed as data-type; its TypeScript type is TextEditorToolbarButtonType.

TextEditorToolbarSeparator and TextEditorSwatch props

useTextEditorContentProps and TEXT_EDITOR_COLORS

It returns id, aria-labelledby, aria-describedby, aria-invalid, aria-disabled and aria-required to spread onto the root. Call it inside the TextEditor. TEXT_EDITOR_COLORS is the readonly tuple ['gray', 'blue', 'orange', 'red', 'green', 'yellow', 'purple', 'sky', 'pink', 'teal'], and TextEditorColor is its union type. It lives in a plain module, so server code can read it.

Styling hooks

The frame is .nu-text-editor with data-invalid and data-disabled; the default content is .nu-text-editor__content (give an engine's root this class). The toolbar is .nu-text-editor-toolbar, items are .nu-text-editor-toolbar__button with data-type, and swatches are .nu-text-editor-swatch with data-color. Supported override points: --nu-text-editor-toolbar-bg, --nu-text-editor-toolbar-ring, --nu-text-editor-item-size (28px) and --nu-text-editor-divider-width (4px).

Accessibility

You must: give every item without visible text a label; name colours in labels and menu items; wire a custom editable root with useTextEditorContentProps, role="textbox" and aria-multiline; pass a translated toolbar aria-label outside English.

Figma mapping

Figma binds every colour to the remote 01-Tokens, 03-Theme and 06-Foundations libraries; code uses the local twins (C19/C22 principle). Item tooltips (top, 2xs, dark) aren't specified in Figma.

08Guidelines and related components

Do and don't

Common mistakes

• Leaving label off icon-only items, so the toolbar reads as a row of unnamed buttons.
• Hard-coding pressed instead of reading it from the engine, so Bold shows on when the cursor is in plain text.
• Putting a contenteditable in the content slot without useTextEditorContentProps, so it loses the Field's label and error.
• Adding tabIndex to items yourself. The toolbar manages one Tab stop; extra tab stops break the pattern.

Related components

• Inputs and fieldsLabel, hint and error for the editor; plain inputs and textareas.
• Dropdown menuMenus behind text, dropdown and colour items.
• TooltipThe hints on toolbar items.
• Button groupPressed toggles outside an editor.