All components (204)

Rich text toolbar

Fields · RichTextToolbar

What it is and when to use it

The toolbar of a rich text editor, without the editor: the application brings the editor (Tiptap, Lexical or any other) and the toolbar only talks to it through state (what is applied where the caret is) and onCommand (what is requested). That keeps the library free of dependencies and makes the toolbar work the same with any editor. The recipes for Tiptap and Lexical are in the editor guide and in the two stories below, with the real editor running.

When to use it

The long text of an admin panel: a product description, a news item, an email template.
marks and blocks to keep only what the content allows (no headings in a short description, for example).
onLinkChange and onImageInsert to show the link and the image, with their panels.
shortcuts with YOUR editor's shortcuts: the toolbar announces and shows them, it does not listen to them.

When not to

Plain text, even if it is long: TextArea.
Code: CodeField.
An action bar over a table or a list: plain Toolbar.

Keyboard: the whole bar is a single Tab stop; inside, Right Arrow and Left Arrow go from button to button, across groups and skipping disabled ones. Enter and Space request the format and focus stays in the bar, which is what the APG asks for. Tabbing back in returns focus to the last button. In the link and image panels, Enter in a field applies and Escape closes.

Accessibility: label is required (there can be several editors on a page). Each format is a ToggleButton with aria-pressed and its shortcut in aria-keyshortcuts; groups are named ("Formatting", "Blocks", "Insert", "History"). Pressing with the mouse does not take focus away from the editor, so the caret and the selection stay where they were. The address of a link or an image is checked before it leaves the toolbar: a javascript: never reaches the editor. The image asks for alternative text unless it is marked as decorative, and then it gets alt="" on purpose. Set aria-controls to the id of the editing area.

Fine-tuning: the bar is a Toolbar (variant, overflow); --amset-richtext-gap is the gap between buttons. For the editor, .amset-richtext__frame (the box with border and focus ring) and .amset-richtext__content (the typography of what is written), with --amset-richtext-min-height.

What it looks like

Applied: bold, heading 2

<RichTextToolbar
  label="Description formatting"
  state={{ active: editor.activos, unavailable: editor.sinUsar }}
  onCommand={(orden) => editor.aplicar(orden)}
  variant="outline"
  size="sm"
  history
  clearFormatting
/>

Props

Import it with import { RichTextToolbar } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`label`required	`string`	Which editor it belongs to: "Description formatting". Required, there can be several on the page.
`onCommand`required	`(command: RichTextCommand) => void`	A format is requested (set or removed) or an action. The editor applies it.
`state`required	`RichTextState`	What is applied where the caret is, read from the editor on every change.
`blocks`	`readonly RichTextBlock[]`	Which blocks are shown. All by default. `[]` removes them.
`className`	`string`	Merged with the library classes; it does not replace them.
`clearFormatting`	`boolean`	"Clear formatting". Shown by default.
`disabled`	`boolean`	The whole bar out of play: the editor is read-only.
`history`	`boolean`	Undo and redo. Shown by default.
`marks`	`readonly RichTextMark[]`	Which marks are shown, in the usual order. All by default. `[]` removes them.
`onImageInsert`	`(image: RichTextImage) => void`	With this the image button appears: it receives the address, already checked, and the alternative text.
`onLinkChange`	`(link: RichTextLink \| null) => void`	With this the link button appears: it receives the new link, already checked, or `null` to remove it.
`overflow`	`"split" \| "scroll"`	`split` (the default) moves what does not fit to another line; `scroll` scrolls sideways.
`shortcuts`	`Readonly<Partial<Record<RichTextCommand, string>>>`	The editor's shortcuts, with `Mod` for Control or Command. They are announced and shown in the tooltip; they are not listened to here.
`size`	`"sm" \| "md"`	—
`variant`	`"outline" \| "raised" \| "flat"`	—

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: