# Toolbar

> Formatting buttons for an editor.

`<WriterToolbar>` formats an editor: pass it the editor's template ref. In plain Vue, import `WriterToolbar`.

## Examples

### Basic

```vue
<script setup lang="ts">
const body = ref("Select some text, then format it.");
const editor = useTemplateRef("editor");
</script>

<template>
  <div class="writer-demo">
    <WriterToolbar
      :editor="editor"
      :items="[
        'heading2',
        'bold',
        'italic',
        'strikethrough',
        'link',
        'bulletList',
        'taskList',
        'undo',
        'redo',
      ]"
    />
    <WriterEditor ref="editor" v-model="body" label="Body" />
  </div>
</template>
```

### Icons

The `item` slot replaces a button's content. Its label stays the accessible name.

```vue
<script setup lang="ts">
const body = ref("Icons instead of words; the names stay for screen readers.");
const editor = useTemplateRef("editor");
const icons = {
  bold: "bold",
  italic: "italic",
  link: "link",
  quote: "quote",
  image: "image",
} as const;
</script>

<template>
  <div class="writer-demo">
    <WriterToolbar :editor="editor" :items="Object.keys(icons) as (keyof typeof icons)[]">
      <template #item="{ command }">
        <Icon :name="icons[command as keyof typeof icons]" />
      </template>
    </WriterToolbar>
    <WriterEditor ref="editor" v-model="body" label="Body" />
  </div>
</template>
```

## Props

| Prop     | Type            | Description                                                                                           |
| -------- | --------------- | ----------------------------------------------------------------------------------------------------- |
| `editor` | editor ref      | The `<WriterEditor>` to format: pass its template ref.                                                |
| `items`  | `CommandName[]` | Commands, in order. Default: headings 2–3, bold, italic, link, code, quote, lists, code block, image. |
| `label`  | `string`        | Accessible name. Default: "Formatting".                                                               |

## Slots

| Slot   | Props                        | Description                       |
| ------ | ---------------------------- | --------------------------------- |
| `item` | `{ command, label, active }` | A button's content, e.g. an icon. |

## Commands

`bold`, `italic`, `strikethrough`, `code`, `link`, `heading1`, `heading2`, `heading3`, `quote`, `bulletList`, `orderedList`, `taskList`, `codeBlock`, `table`, `divider`, `image`, `footnote`, `undo`, `redo`.

Headings, quotes and lists replace each other on a line. `image` opens the file picker when the editor has `upload`, and otherwise inserts an empty image card.

For a different toolbar entirely, call the editor's `run(command)` yourself. `ToolbarEditor` is the type of what the toolbar needs from an editor.

## Accessibility

`role="toolbar"`, with one tab stop: arrow keys, Home and End move between buttons. Formatting buttons show `aria-pressed`; `undo` and `redo` are `aria-disabled` when there's nothing to undo or redo. Buttons don't take focus from the editor.