Block editor

01Preview

A real editor with sample notes. Type / on an empty line for the block menu, select text for the formatting toolbar, click into the table for its toolbar, and click the formula to edit it. AI Summary, Run and image upload use demo stand-ins here.

<h1>My Notes</h1><p>A classic example is the Eames Lounge Chair. It is celebrated for its elegant looks, but every curve and material was chosen for comfort and durability. The form and function are so intertwined that they become inseparable. That synergy is often the hallmark of truly great design.</p><ul data-type="taskList"><li data-type="taskItem" data-checked="false"><p>Designed to be useful or practical rather than attractive.</p></li><li data-type="taskItem" data-checked="true"><p>Read the chapter on affordances.</p></li></ul><table><tbody><tr><th><p>Principle</p></th><th><p>Question to ask</p></th><th><p>Example</p></th></tr><tr><td><p>Affordance</p></td><td><p>What does it invite me to do?</p></td><td><p>A handle invites pulling</p></td></tr><tr><td><p>Feedback</p></td><td><p>Did my action work?</p></td><td><p>A button changes colour</p></td></tr></tbody></table><pre><code class="language-python">def golden_ratio(width):
    return width / 1.618</code></pre><div data-type="callout" data-emoji="💡"><div class="nu-block-callout__content">Form and function should be designed together, not one after the other.</div></div><div data-type="block-math" data-latex="\frac{a + b}{a} = \frac{a}{b} = \varphi"></div><p></p>

02Installation

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

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

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

import '@nuton/tokens/tokens.css'
import '@nuton/ui/styles.css'

TipTap 3 and its table, task-list, image, maths and code extensions, KaTeX and lowlight install with @nuton/ui, pinned to exact versions (ADR 0007). Apps that never import BlockEditor don't bundle them. Maths renders as MathML, so no KaTeX stylesheet or fonts are needed.

03Usage

import { BlockEditor } from '@nuton/ui'

export function LessonNotes({ saved, save }: { saved: string; save: (html: string) => void }) {
  return (
    <BlockEditor
      aria-label="Lesson notes"
      defaultValue={saved}
      onChange={save}
      onAiSummary={(editor) => summarise(editor.getText())}
      onImageUpload={(file) => uploadToStorage(file)} // resolves with the image URL
    />
  )
}

• The value is HTML. The first block is the title (Figma “My Notes”); pass withTitle={false} for notes without one.
• Connect the app's services: onAiSummary, onRunCode, onImageUpload and onFileUpload. Each feature only appears when its handler is set.
• Save on change (debounced) rather than with a submit button, as people expect from note apps. Pass name when it lives in a form.
• Sanitize stored HTML on the server before showing it to anyone else.
• For a short formatted answer in a form, use Text editor instead.

04Variants and sizes

The editor fills its column (Figma 698 wide). Content is made of blocks.

Blocks and the slash menu

Typing after / filters the menu (“/check” → Checklist). Markdown shortcuts also work: # , ## , - , 1. , [ ] , > , ``` and ---.

Measurements

Empty notes

A new note shows the title placeholder and Figma's prompt, “Start writing or type ‘/’ to see commands”.

<BlockEditor aria-label="New lesson notes" onAiSummary={summarise} />

05States and interactions

Read-only

<BlockEditor aria-label="Shared notes" disabled defaultValue={sharedHtml} />

06Composition examples

Connecting your services

<BlockEditor
  aria-label="Lesson notes"
  defaultValue={note.html}
  onChange={debounce(saveNote, 800)}
  // AI Summary: read the text, insert the result as a callout
  onAiSummary={async (editor) => {
    const summary = await api.summarise(editor.getText())
    editor.chain().focus().insertContent({ type: 'callout', attrs: { emoji: '✨' }, content: [{ type: 'text', text: summary }] }).run()
  }}
  // Run: return output to show it under the code block
  onRunCode={(code, language) => api.runCode({ code, language })}
  onImageUpload={(file) => storage.upload(file).then((r) => r.url)}
  onFileUpload={(file) => storage.upload(file).then((r) => ({ url: r.url, name: file.name }))}
/>

07API reference

Props

Also exported: BLOCK_EDITOR_LABELS, BLOCK_EDITOR_LANGUAGES (code languages), BLOCK_EDITOR_FONT_SIZES and filterBlockCommands.

Accessibility

You must: give the editor a name (Field label or aria-label), ask for alt text when people add images, and translate labels outside English.

Figma mapping

08Guidelines and related components

Do and don't

Related components

• Text editorA rich-text field with a fixed toolbar, for forms.
• CheckboxThe control behind checklist items.
• ModalUsed by the link, image and maths dialogs.