Document Editor

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 document-editor

Usage#

Anatomy#

import {
  DocumentEditor,
  DocumentEditorCanvas,
  DocumentEditorHeader,
  DocumentEditorIcon,
  DocumentEditorHeaderActions,
  DocumentEditorHeaderAction,
  DocumentEditorTitle,
  DocumentEditorMeta,
  DocumentEditorMetaItem,
  DocumentEditorContent,
  DocumentEditorBubbleMenu,
  DocumentEditorBubbleButton,
  DocumentEditorBubbleSeparator,
  DocumentEditorTableMenu,
} from "@/components/ui/document-editor"

<DocumentEditor>
  <DocumentEditorCanvas>
    <DocumentEditorHeader>
      <DocumentEditorHeaderActions>
        <DocumentEditorHeaderAction />
      </DocumentEditorHeaderActions>
      <DocumentEditorIcon />
      <DocumentEditorTitle />
      <DocumentEditorMeta>
        <DocumentEditorMetaItem />
      </DocumentEditorMeta>
    </DocumentEditorHeader>
    <DocumentEditorContent />
    <DocumentEditorBubbleMenu>
      <DocumentEditorBubbleSeparator />
      <DocumentEditorBubbleButton />
    </DocumentEditorBubbleMenu>
    <DocumentEditorTableMenu />
  </DocumentEditorCanvas>
</DocumentEditor>

Title and header#

The title is a field of its own, not the first block, so it can never be deleted or turned into a list. It grows with its text and moves into the body on Enter. Above it, DocumentEditorHeaderActions rest hidden and fade in on hover,DocumentEditorIcon holds the page emoji, and DocumentEditorMeta lays out chips under the title.

Width#

width sets the measure: page holds a line to 65 characters, wide opens to 900px for tables and images, and full fills the container. Switching slides the measure instead of jumping.

Slash menu#

With slashCommandExtension(), a / at the start of a block or after a space opens the block menu at the caret. Typing filters it by title and keyword, arrows move, Enter or Tab inserts. Markdown shortcuts work too: #, -, [], >, ```.

Every block it offers, painted with SlashMenuList, the same list on its own for a picker of your own.

commands decides what the menu offers: filter the registry, rename it, or add a BlockCommand of your own.

Bubble menu#

Select text and the bar rises over it. Highlight offers four colours mixed from the status tokens. onComment adds a Comment button, and children land at the end of the bar: the slot for an Ask AI action.

To-do list#

Type [] and a space. Items nest with Tab, and a checked one fades to the muted ink with a line through it.

Toggle#

A summary line that opens to reveal the blocks inside. Whether it is open is saved with the document.

Image#

An empty image block offers upload and a link field; pasting or dropping a picture anywhere inserts one. Select an image to align it, drag its edges to resize it, and add a caption. Pass onUpload to store files instead of previewing them locally.

Table#

A stroked grid, a faint header row and resizable columns. Selected cells take an ink wash, and DocumentEditorTableMenu adds grips on the hovered row and column, bars that add a row or a column, and the table's options at its corner.

Columns, contents and link cards#

Columns put two or three stacks of blocks side by side and fold to one on phones. The contents block lists the page's headings live and jumps to them. A link card turns a URL into a calm card with its title and domain; paste a bare link on an empty line to make one.

Mentions#

Type @ for a list of people and pages, grouped, filtered as you type. The pick lands as a quiet chip: an @ before a person, the emoji before a page. A click on a page chip calls onOpen.

Code block and divider#

The code block shows its language and a copy button on hover. A divider takes a soft ring when selected, so it can be moved or deleted like any block.

Read-only#

editable={false} renders the same page for reading. The bubble and table menus stay out, the title is read-only and checkboxes stop toggling, so the composition can stay as it is.

Density#

compact suits a document inside an app screen, comfortable a page given the whole window. It scales the title, the body, the headings and every gap between blocks.

Labels#

Each part takes its strings where it is set up: the root's labels, the bubble's labels, the blocks' labels and the slash menu's commands and emptyLabel.

Word count#

useDocumentEditorStats returns the words, characters and minutes of reading of the live document, for a status bar anywhere inside the editor.

API reference#

FAQ#