# Introduction

Source: /getting-started/introduction

> What Echo Editor is, what it ships with and how it is built.

Echo Editor is a WYSIWYG rich-text editor for **Vue 3**. It wraps [Tiptap 3](https://tiptap.dev) (and therefore ProseMirror) in a ready-to-use component with a toolbar, bubble menus, a slash menu and a drag handle — all styled with [shadcn-vue](https://shadcn-vue.com) and Tailwind CSS 4.

## Highlights

- **Batteries included** — 40+ extensions: headings, lists, task lists, tables, columns, code blocks with syntax highlighting, images, video, embeds, find & replace, HTML source editing, print, fullscreen and more.
- **Fast** — Tiptap is shared with your app instead of bundled, feature UIs load on demand, and the toolbar re-evaluates at most once per animation frame. See [Performance](/guide/performance).
- **Markdown & export** — `v-model` in HTML, JSON, text or Markdown, plus export to PDF, Markdown, HTML, RTF, text and JSON.
- **Collaboration** — Y.js-powered real-time editing with remote carets, shipped as a separate entry point.
- **AI** — an inline AI menu that streams completions from any model or backend.
- **Accessible & international** — labelled controls, keyboard-navigable toolbar, screen-reader announcements, 11 languages and RTL support.
- **Extensible** — every button comes from an extension, and `definePlugin()` bundles your own extensions, buttons, slash commands and translations.

## How it fits together

| Layer | Responsibility |
| --- | --- |
| `<EchoEditor>` | Component: creates the Tiptap editor, renders toolbar, menus and dialogs, syncs `v-model`. |
| Extensions | Tiptap extensions extended with a `button` view — each one contributes schema, commands, shortcuts **and** its toolbar UI. |
| Composables | `useEditorState`, `useTheme`, `useTiptapStore`, `useLocale` for building your own UI around the editor. |
| Plugins | `definePlugin()` packages extensions, buttons, slash commands and translations for reuse. |

## Requirements

- Vue `3.5+`
- A bundler that understands ES modules and CSS imports (Vite, Nuxt, Rsbuild, webpack 5 …)
- Node.js `20.19+` for development
> Coming from `0.x`? Read the [migration guide](/getting-started/migration) — version 1.0 moves to Tiptap 3.

# Installation

Source: /getting-started/installation

> Install the package and import the styles.

### Install the package

```bash
pnpm add vue-echo-editor
```

Tiptap, ProseMirror and the UI primitives are regular dependencies and are installed automatically. They are **not** bundled into Echo Editor, so if your app already uses Tiptap 3 you get a single shared copy.

### Import the styles

Import the stylesheet once, for example in `main.ts`:

```ts [main.ts]
import 'vue-echo-editor/style.css'
```

### (Optional) register the component globally

```ts [main.ts]
import { createApp } from 'vue'
import { EchoEditorPlugin } from 'vue-echo-editor'
import 'vue-echo-editor/style.css'
import App from './App.vue'

createApp(App).use(EchoEditorPlugin).mount('#app')
```

This registers `<EchoEditor>` (and the legacy `<echo-editor>` tag). You can also import `EchoEditor` directly where you use it — that is what the rest of these docs do.

## Optional peer dependencies

Only install these when you use the matching feature:

| Feature | Packages |
| --- | --- |
| [Collaboration](/guide/collaboration) | `yjs`, `@tiptap/y-tiptap`, `@tiptap/extension-collaboration`, `@tiptap/extension-collaboration-caret` and a provider such as `y-websocket` |

```bash
pnpm add yjs y-websocket @tiptap/y-tiptap @tiptap/extension-collaboration @tiptap/extension-collaboration-caret
```

## Package entry points

| Import | Contents |
| --- | --- |
| `vue-echo-editor` | Component, extensions, composables, locales, plugin API |
| `vue-echo-editor/collaboration` | `CollaborationKit`, `CollaborationUsers`, `useCollaborationUsers` |
| `vue-echo-editor/style.css` | Editor styles (scoped to `.echo-editor`) |

Both ESM and CommonJS builds are published, with full TypeScript declarations.

# Quick start

Source: /getting-started/quick-start

> Render your first editor with v-model in under a minute.

## A minimal editor

```vue [RichEditor.vue]
<script setup lang="ts">
import { ref } from 'vue'
import { EchoEditor, BaseKit, History, Heading, Bold, Italic, Underline, Link, BulletList, OrderedList } from 'vue-echo-editor'
import 'vue-echo-editor/style.css'

const content = ref('<p>Hello <strong>Echo Editor</strong>!</p>')

// Create the extensions once — never inside a computed or a template expression
const extensions = [BaseKit, History, Heading, Bold, Italic, Underline, Link, BulletList, OrderedList]
</script>

<template>
  <EchoEditor v-model="content" :extensions="extensions" :max-height="480" />
</template>
```

`BaseKit` is required: it provides the document model, paragraphs, placeholder, character count and the bubble menu. Everything else is opt-in — **the toolbar is built from the extensions you register**, in the order you register them.

## Choose an output format

```vue
<EchoEditor v-model="html" output="html" :extensions="extensions" />
<EchoEditor v-model="json" output="json" :extensions="extensions" />
<EchoEditor v-model="text" output="text" :extensions="extensions" />
<EchoEditor v-model="md" output="markdown" :extensions="[...extensions, Markdown]" />
```

## Group toolbar buttons

Every extension accepts `spacer` (a separator before its button) and `divider` (a separator after it):

```ts
const extensions = [
  BaseKit,
  History,
  Heading.configure({ spacer: true }),
  Bold,
  Italic,
  Underline,
  Link.configure({ spacer: true }),
  BulletList,
  OrderedList,
]
```

Hide an extension's button while keeping its functionality with `toolbar: false`:

```ts
Bold.configure({ toolbar: false }) // Mod-B still works
```

## Access the Tiptap editor

```vue
<script setup lang="ts">
import { shallowRef } from 'vue'
import type { EditorInstance } from 'vue-echo-editor'

const editor = shallowRef<EditorInstance>()
</script>

<template>
  <EchoEditor :extensions="extensions" @create="({ editor: e }) => (editor = e)" />
  <button @click="editor?.chain().focus().toggleBold().run()">Bold</button>
</template>
```

You can also use a template ref: `editorRef.value.editor`.

## Next steps

  Every prop, event and slot.

  The full extension catalogue.

  Use Echo Editor in a Nuxt app.

  Markdown as your v-model.

# Nuxt

Source: /getting-started/nuxt

> Use Echo Editor in a Nuxt 3 / Nuxt 4 application.

Echo Editor is a browser component (it needs the DOM for ProseMirror), so render it on the client.

### Install

```bash
pnpm add vue-echo-editor
```

### Add the styles

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  css: ['vue-echo-editor/style.css'],
  build: {
    transpile: ['vue-echo-editor'],
  },
})
```

### Create a client-only component

Name the file with a `.client.vue` suffix, or wrap the editor in `<ClientOnly>`:

```vue [components/RichEditor.client.vue]
<script setup lang="ts">
import { EchoEditor, BaseKit, History, Heading, Bold, Italic, Link, BulletList } from 'vue-echo-editor'

const model = defineModel<string>({ default: '' })
const extensions = [BaseKit, History, Heading, Bold, Italic, Link, BulletList]
</script>

<template>
  <EchoEditor v-model="model" :extensions="extensions" />
</template>
```

### Use it

```vue [pages/index.vue]
<script setup lang="ts">
const content = ref('<p>Hello from Nuxt</p>')
</script>

<template>
  <RichEditor v-model="content" />
</template>
```

## Rendering stored content on the server

To display saved documents during SSR (for SEO or a read-only view) you do not need the editor. Render the stored HTML inside an element with the `EchoContentView` class so it gets the editor's typography:

```vue
<template>
  <div class="echo-editor echo-editor-ui">
    <div class="EchoContentView" v-html="article.html" />
  </div>
</template>
```
> Always sanitize user-generated HTML on the server (for example with DOMPurify or `sanitize-html`) before rendering it with `v-html`.
## Colour mode

Pass Nuxt's colour mode to the editor so it follows your site theme:

```vue
<script setup lang="ts">
const colorMode = useColorMode()
</script>

<template>
  <EchoEditor :dark="colorMode.value === 'dark'" :extensions="extensions" />
</template>
```

# Migrating to v1

Source: /getting-started/migration

> Upgrade from Echo Editor 0.x (Tiptap 2) to 1.x (Tiptap 3).

Version 1.0 moves Echo Editor to **Tiptap 3** and modernises the build. Most apps only need to bump the package; custom extensions and deep integrations may need the changes below.

## TL;DR

```bash
pnpm add vue-echo-editor@^1
```

- Your `<EchoEditor>` usage, props, `v-model` and built-in extensions keep working.
- If you wrote **custom Tiptap extensions**, follow the [Tiptap v2 → v3 upgrade guide](https://tiptap.dev/docs/guides/upgrade-tiptap-v2).
- The default UI language is now **English** — call `locale.setLang('zhHans')` for Chinese.

## Breaking changes

### Tiptap 3

All `@tiptap/*` packages are now v3. The most common changes for custom code:

```diff
- import TableRow from '@tiptap/extension-table-row'
+ import { TableRow } from '@tiptap/extension-table'

- import BulletList from '@tiptap/extension-bullet-list'
+ import { BulletList } from '@tiptap/extension-list'

- import Placeholder from '@tiptap/extension-placeholder'
+ import { Placeholder } from '@tiptap/extensions'

- editor.commands.setContent(html, false)
+ editor.commands.setContent(html, { emitUpdate: false })

- const pos = getPos()
+ const pos = getPos()
+ if (typeof pos !== 'number') return   // getPos() can now return undefined
```

Echo Editor re-exports `TableRow`, `TableCell`, `TableHeader` and `TableCellBackground` for convenience.

### tippy.js → Floating UI

`tippy.js` was removed. Every popup (bubble menus, slash menu, drag handle) now uses [Floating UI](https://floating-ui.com).

If you imported the internal `DragHandlePlugin`, rename `tippyOptions` to `computePositionConfig`:

```diff
  DragHandlePlugin({
    editor,
    element,
-   tippyOptions: { placement: 'left-start' },
+   computePositionConfig: { placement: 'left-start' },
  })
```

### Build output

| 0.x | 1.x |
| --- | --- |
| `lib/echo-editor.es.js` | `lib/echo-editor.js` |
| `lib/echo-editor.umd.js` | `lib/echo-editor.cjs` (UMD removed, like Tiptap 3) |
| Tiptap bundled inside | Tiptap installed as a dependency and shared with your app |

Imports through the package name (`import … from 'vue-echo-editor'`) are unaffected.

### Default language

The default language changed from `zhHans` to `en`, and `locale.setLang()` is now **async** because additional languages are lazy-loaded:

```ts
import { locale } from 'vue-echo-editor'

await locale.setLang('zhHans')
```

### Per-editor UI state

Fullscreen, preview, source-code, AI-menu and other UI state used to be global, so two editors on one page affected each other. It is now per editor. If you called `useTiptapStore()` outside a component, pass the editor:

```diff
- const { toggleFullscreen } = useTiptapStore()
+ const { toggleFullscreen } = useTiptapStore(editor)
```

### History

`History` is now built on Tiptap's `UndoRedo` extension (still named `history`, also exported as `UndoRedo`). The default `depth` increased from 10 to 100.

### Icons

Icons moved from `lucide-vue-next` to its successor `@lucide/vue`. This only matters if you passed Lucide components to custom buttons.

## Fixed in 1.0

These worked incorrectly in 0.x and may change behaviour you relied on:

- `@enter` never fired — it now does (Shift+Enter still inserts a new line).
- Ordered list styles (roman, latin …) were lost when loading HTML.
- Popover toolbar buttons rendered a `<button>` inside a `<button>`.
- The AI prompt form reloaded the page on submit.

## New in 1.0

- [Markdown](/guide/markdown) `v-model` and `editor.getMarkdown()`
- [Export](/guide/export) to PDF, Markdown, HTML, RTF, text and JSON
- [Collaboration](/guide/collaboration) via `vue-echo-editor/collaboration`
- [Plugins](/api/plugins) with `definePlugin()`
- [9 new languages](/guide/i18n) and RTL support
- `useEditorState()` for building fast custom UI
- New props `label`, `autofocus`, `editorProps` and events `create`, `focus`, `blur`

# Configuration

Source: /guide/configuration

> Props, events, slots and the exposed editor instance of <EchoEditor>.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `modelValue` | `string \| JSONContent` | `''` | Content, bound with `v-model`. Format depends on `output`. |
| `output` | `'html' \| 'json' \| 'text' \| 'markdown'` | `'html'` | Format emitted through `v-model`. `markdown` requires the [`Markdown`](/guide/markdown) extension. |
| `extensions` | `AnyExtension[]` | `[]` | Extensions to register. **Create this array once.** |
| `disabled` | `boolean` | `false` | Read-only mode. Hides bubble menus and disables toolbar buttons. |
| `hideToolbar` | `boolean` | `false` | Hide the toolbar. |
| `hideMenubar` | `boolean` | `true` | Hide the File / Edit / View / Insert / Format menubar. |
| `hideBubble` | `boolean` | `false` | Disable bubble menus and the drag handle. |
| `removeDefaultWrapper` | `boolean` | `false` | Emit `''` (or `{}`) instead of `<p></p>` when the document is empty. |
| `minHeight` | `string \| number` | — | Minimum content height (`number` → px). |
| `maxHeight` | `string \| number` | — | Maximum content height; content scrolls beyond it. |
| `maxWidth` | `string \| number` | — | Maximum content width, centred. |
| `dark` | `boolean` | follows system | Force dark or light mode. |
| `theme` | `Theme` | `'zinc'` | Accent colour, see [Theming](/guide/theming). |
| `radius` | `0 \| 0.25 \| 0.5 \| 0.75 \| 1` | `0.5` | Border radius in `rem`. |
| `label` | `string` | localized "Please input content" | Accessible name (`aria-label`) of the editable area. |
| `autofocus` | `boolean \| 'start' \| 'end' \| 'all' \| number` | `false` | Focus the editor on mount. |
| `editorProps` | `EditorProps` | — | Extra ProseMirror props. `attributes` are merged; `handleKeyDown` runs after the built-in Enter handling. |
| `editorClass` | `string \| string[] \| object` | — | Class for the root element. |
| `contentClass` | `string \| string[] \| object` | — | Class for the content element. |

## Events

| Event | Payload | When |
| --- | --- | --- |
| `update:modelValue` | `string \| JSONContent` | Content changed (throttled to 200 ms, flushed on blur and unmount). |
| `change` | `{ editor, output }` | Same timing as `update:modelValue`, with the editor instance. |
| `create` | `{ editor }` | The Tiptap editor was created. |
| `focus` | `{ editor, event }` | The editor received focus. |
| `blur` | `{ editor, event }` | The editor lost focus. |
| `enter` | — | Enter was pressed (without Shift). Only intercepted when a listener is attached — useful for chat inputs. |

```vue
<EchoEditor
  v-model="message"
  :extensions="extensions"
  hide-toolbar
  @enter="send"
/>
```

## Slots

| Slot | Props | Description |
| --- | --- | --- |
| `footer` | `{ editor }` | Rendered in the footer next to the character counter (requires `characterCount`, enabled by default in `BaseKit`). |

```vue
<EchoEditor v-model="content" :extensions="extensions">
  <template #footer="{ editor }">
    <span class="text-xs text-muted-foreground">{{ editor.storage.characterCount.words() }} words</span>
  </template>
</EchoEditor>
```

## Exposed instance

```vue
<script setup lang="ts">
import { useTemplateRef } from 'vue'

const echo = useTemplateRef('echo')

function insertSignature() {
  echo.value?.editor.chain().focus('end').insertContent('<p>— Sent with Echo Editor</p>').run()
}
</script>

<template>
  <EchoEditor ref="echo" :extensions="extensions" />
</template>
```

`editor` is a regular [Tiptap `Editor`](https://tiptap.dev/docs/editor/api/editor): use its commands, `getHTML()`, `getJSON()`, `getText()`, `getMarkdown()` (with the `Markdown` extension), events and storage.

## Configuring BaseKit

`BaseKit` bundles the essentials. Each part can be configured or disabled:

```ts
BaseKit.configure({
  placeholder: { placeholder: 'Start writing…', showOnlyCurrent: true },
  characterCount: { limit: 10_000 },
  dropcursor: { color: '#6366f1' },
  focus: false,          // no `.focus` class on the active node
  trailingNode: false,   // don't force an empty paragraph at the end
})
```

| Option | Default | Description |
| --- | --- | --- |
| `placeholder` | on | [Placeholder](https://tiptap.dev/docs/editor/extensions/functionality/placeholder) options or `false`. |
| `characterCount` | on | [CharacterCount](https://tiptap.dev/docs/editor/extensions/functionality/character-count) options (`limit`, `mode`) or `false`. |
| `focus` | on | Adds a `focus` class to the node with the cursor. |
| `dropcursor` / `gapcursor` | on | Drag-and-drop and gap cursors. |
| `hardBreak`, `paragraph`, `listItem`, `textStyle` | on | Core nodes and marks. |
| `trailingNode` | on | Keeps an empty paragraph at the end of the document. |
| `textBubble`, `selection`, `highlightParagraph` | on | Bubble-menu text type switcher and selection helpers. |
| `bubble` | — | Customise the [bubble menu](/guide/toolbar-and-menus#bubble-menu). |

# Toolbar & menus

Source: /guide/toolbar-and-menus

> Customise the toolbar, bubble menu, slash menu, drag handle and menubar.

## Toolbar

The toolbar is generated from your extensions: every extension with a `button` contributes one or more controls, **in the order of the `extensions` array**.

```ts
const extensions = [
  BaseKit,
  History,                             // undo, redo
  Heading.configure({ spacer: true }), // separator before
  Bold,
  Italic,
  Link.configure({ divider: true }),   // separator after
  Table.configure({ toolbar: false }), // no button, feature still available
]
```

| Option (all extensions) | Description |
| --- | --- |
| `spacer` | Render a separator **before** the button. |
| `divider` | Render a separator **after** the button. |
| `toolbar` | `false` hides the button but keeps the extension. |
| `button` | Replace the button entirely (see [Custom extensions](/extensions/custom)). |

The toolbar follows the WAI-ARIA toolbar pattern: <kbd>←</kbd> / <kbd>→</kbd> move between controls, <kbd>Home</kbd> / <kbd>End</kbd> jump to the ends. On touch devices it becomes a horizontally scrollable strip with 40 px touch targets.

### Replacing a button

```ts
import { ActionButton, Bold } from 'vue-echo-editor'

Bold.configure({
  button: ({ editor, t }) => ({
    component: ActionButton,
    componentProps: {
      icon: 'Bold',
      tooltip: t('editor.bold.tooltip'),
      shortcutKeys: ['mod', 'B'],
      action: () => editor.chain().focus().toggleBold().run(),
      isActive: () => editor.isActive('bold'),
      disabled: !editor.can().toggleBold(),
    },
  }),
})
```

## Bubble menu

Selecting text shows a bubble menu. Its content is configured on `BaseKit` per node type:

```ts
BaseKit.configure({
  bubble: {
    list: {
      text: ['bold', 'italic', 'underline', 'divider', 'link', 'color', 'highlight'],
      video: ['video-size-small', 'video-size-medium', 'video-size-large', 'divider', 'remove'],
    },
  },
})
```

Entries are extension names (`bold`, `link`, `color`, `AI`, `textAlign` …), `divider`, `text-bubble` (the block-type switcher) or the built-in video actions. Extensions that aren't registered are skipped automatically.

Links, tables, images and column layouts get their own context menus when those extensions are registered. On touch devices the bubble menu opens **below** the selection so it doesn't collide with the native selection toolbar.

## Slash menu

Register `SlashCommand` and type <kbd>/</kbd> at the start of an empty line.

```ts
import { SlashCommand } from 'vue-echo-editor'
import type { Group } from 'vue-echo-editor'

SlashCommand.configure({
  getCommandGroups: ({ presetGroups, editor, lang }) => [
    ...presetGroups,
    {
      name: 'snippets',
      title: 'Snippets',
      commands: [
        {
          name: 'greeting',
          label: 'Greeting',
          aliases: ['hello', 'hi'],
          iconName: 'Sparkles',
          action: ({ editor, range }) => editor.chain().focus().deleteRange(range).insertContent('Hello 👋').run(),
        },
      ],
    },
  ] satisfies Group[],
})
```

[Plugins](/api/plugins) can also contribute slash commands without touching this configuration.

## Drag handle

A drag handle appears to the left of the hovered block (desktop only). It moves blocks by drag and drop and opens a block menu: delete, clear formatting, copy, duplicate, alignment and indentation. The `+` button inserts a new line and opens the slash menu.

Disable it — together with bubble menus — with `hide-bubble`.

## Menubar

A classic File / Edit / View / Insert / Format menubar is available:

```vue
<EchoEditor :extensions="extensions" :hide-menubar="false" />
```

Menu entries only appear when the extension they need is registered.

# Markdown

Source: /guide/markdown

> Read and write Markdown with v-model, commands and the official @tiptap/markdown parser.

The `Markdown` extension wraps the official [`@tiptap/markdown`](https://tiptap.dev/docs/editor/markdown) package (MarkedJS under the hood) for bidirectional Markdown support.

## Markdown as v-model

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { EchoEditor, BaseKit, History, Heading, Bold, Italic, Link, BulletList, OrderedList, TaskList, CodeBlock, Markdown } from 'vue-echo-editor'

const markdown = ref('# Hello\n\nThis is **Markdown**.')

const extensions = [BaseKit, History, Heading, Bold, Italic, Link, BulletList, OrderedList, TaskList, CodeBlock, Markdown]
</script>

<template>
  <EchoEditor v-model="markdown" output="markdown" :extensions="extensions" />
</template>
```

With `output="markdown"`, the initial `modelValue` is parsed as Markdown and every update emits Markdown.

## Commands & API

```ts
// Serialise
const md = editor.getMarkdown()

// Replace the document with Markdown
editor.commands.setContent('## New content', { contentType: 'markdown' })

// Insert Markdown at the cursor
editor.commands.insertContent('- item 1\n- item 2', { contentType: 'markdown' })
```

## Supported syntax

Headings, paragraphs, bold, italic, strikethrough, inline code, links, images, blockquotes, bullet / ordered / task lists, horizontal rules, fenced code blocks (with language) and tables. Unknown HTML embedded in Markdown is parsed with the regular HTML rules.
> Markdown cannot represent everything the editor can — text colours, font sizes, column layouts or cell background colours are dropped when serialising. Use `html` or `json` output if you need a lossless format.
## Custom syntax

Every Tiptap node or mark can define `parseMarkdown` and `renderMarkdown`. For example, the built-in `CodeBlock` does:

```ts
CodeBlock.extend({
  markdownTokenName: 'code',
  parseMarkdown: token => ({ type: 'codeBlock', attrs: { language: token.lang, code: token.text } }),
  renderMarkdown: node => '```' + node.attrs.language + '\n' + node.attrs.code + '\n```',
})
```

See the Tiptap docs on [custom Markdown tokenizers](https://tiptap.dev/docs/editor/markdown) for advanced cases.

# Export

Source: /guide/export

> Export documents to PDF, Markdown, HTML, RTF, plain text and JSON.

## Toolbar button

```ts
import { Export, Markdown } from 'vue-echo-editor'

const extensions = [
  BaseKit,
  // …
  Markdown, // enables the Markdown option
  Export.configure({
    formats: ['pdf', 'markdown', 'html', 'text', 'rtf', 'json'],
    filename: () => `notes-${new Date().toISOString().slice(0, 10)}`,
  }),
]
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `formats` | `ExportFormat[]` | all | Formats shown in the dropdown, in order. |
| `filename` | `string \| () => string` | `'document'` | File name without extension. |

## Formats

| Format | How it works |
| --- | --- |
| `pdf` | Opens the browser print dialog with a clean, styled copy of the document — choose **Save as PDF**. No extra dependencies. |
| `markdown` | `editor.getMarkdown()` — requires the `Markdown` extension. |
| `html` | A standalone HTML file that embeds the editor's content styles. |
| `text` | Plain text with blank lines between blocks. |
| `rtf` | Rich Text Format (headings, bold/italic/underline/strike, sub/superscript, lists, task lists, quotes, code, tables). Opens in Word, Pages and LibreOffice. |
| `json` | The Tiptap/ProseMirror JSON document — lossless. |

## Programmatic export

```ts
// Through the command (downloads a file)
editor.commands.exportDocument('markdown', 'my-notes')

// Or get the content without downloading
import { serialize, jsonToRTF, toPlainText, downloadFile } from 'vue-echo-editor'

const { content, mimeType, extension } = serialize(editor, 'rtf', 'report')
await fetch('/api/documents', { method: 'POST', body: content, headers: { 'content-type': mimeType } })
```

## Word (.docx)

DOCX export needs a heavier converter, so it's not built in. The [examples app](https://github.com/kemboi22/vue-echo-editor/tree/main/examples/extensions/ExportWord) contains a complete `ExportWord` [plugin](/api/plugins) built with `prosemirror-docx` that you can copy.

# Images & uploads

Source: /guide/uploads

> Upload images, videos and Word documents to your own storage.

Echo Editor never uploads anything by itself — you provide the upload function, so files go wherever you want (S3, Cloudinary, your API …).

## Images

```ts
import { Image, ImageUpload } from 'vue-echo-editor'

const extensions = [
  BaseKit,
  Image,
  ImageUpload.configure({
    // Return the public URL of the uploaded file
    upload: async (file: File) => {
      const body = new FormData()
      body.append('file', file)
      const res = await fetch('/api/upload', { method: 'POST', body })
      const { url } = await res.json()
      return url
    },
    acceptMimes: ['image/png', 'image/jpeg', 'image/webp', 'image/gif'],
    maxSize: 5 * 1024 * 1024, // bytes
  }),
]
```

`Image` renders resizable images with an image bubble menu (flip, size presets, alignment, remove). Images can also be pasted or dropped into the editor.

## Videos

```ts
import { Video, VideoUpload } from 'vue-echo-editor'

VideoUpload.configure({
  upload: async (files: File[]) => {
    const urls = await Promise.all(files.map(uploadToStorage))
    return urls.map((src, i) => ({ src, alt: files[i].name }))
  },
})
```

## Word documents

`ImportWord` imports `.docx` files. Provide a `convert` function (for example calling a server that uses `mammoth`) and an optional `upload` for embedded images:

```ts
import { ImportWord } from 'vue-echo-editor'

ImportWord.configure({
  convert: async (file: File) => {
    const body = new FormData()
    body.append('file', file)
    return (await fetch('/api/docx-to-html', { method: 'POST', body })).text()
  },
  limit: 10 * 1024 * 1024,
})
```

## Embeds

`Iframe` embeds services such as YouTube, Bilibili, Figma, CodePen and more from a pasted link.

# AI assistant

Source: /guide/ai

> Stream completions from any model into the inline AI menu.

The `AI` extension adds an **Ask AI** entry to the toolbar and bubble menu. It opens an inline prompt with shortcuts (improve, shorten, translate, change tone …); the response streams in and can be inserted below or replace the selection.

## Connect a model

Provide a `completions(history, signal)` function that returns an **async iterable** of chunks. Chunks can be plain strings, OpenAI-style `choices[0].delta.content` objects, or `{ text }` objects — so any provider works.
> Never ship API keys to the browser. Call your own backend and let it talk to the model provider.
### Your own backend (recommended)

```ts
import { AI } from 'vue-echo-editor'

AI.configure({
  completions: async function* (history, signal) {
    const res = await fetch('/api/ai', {
      method: 'POST',
      body: JSON.stringify({ messages: history }),
      headers: { 'content-type': 'application/json' },
      signal,
    })
    const reader = res.body!.pipeThrough(new TextDecoderStream()).getReader()
    while (true) {
      const { value, done } = await reader.read()
      if (done) return
      yield value // plain text chunks
    }
  },
})
```

### Example server with Claude

```ts [server/api/ai.post.ts]
import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic() // reads ANTHROPIC_API_KEY

export default defineEventHandler(async event => {
  const { messages } = await readBody(event)
  const stream = client.messages.stream({
    model: 'claude-sonnet-5-5',
    max_tokens: 2048,
    system: 'You are a writing assistant. Answer in HTML, preserving formatting.',
    messages,
  })

  return new ReadableStream({
    async start(controller) {
      for await (const chunk of stream) {
        if (chunk.type === 'content_block_delta' && chunk.delta.type === 'text_delta') {
          controller.enqueue(new TextEncoder().encode(chunk.delta.text))
        }
      }
      controller.close()
    },
  })
})
```

### OpenAI-compatible SDKs

The OpenAI SDK's streaming response is already an async iterable of `choices[0].delta.content` chunks, so it can be returned directly (from a trusted environment):

```ts
AI.configure({
  completions: (history, signal) =>
    openai.chat.completions.create({ model: 'gpt-5', messages: history, stream: true }, { signal }),
})
```

## Custom shortcuts

```ts
AI.configure({
  completions,
  shortcuts: [
    {
      label: 'Marketing',
      icon: 'Sparkles',
      children: [
        { label: 'Write a tagline', prompt: 'Write a short, catchy tagline for this text.' },
        { label: 'SEO title', prompt: 'Suggest an SEO-friendly title (max 60 characters).' },
      ],
    },
  ],
})
```

Custom shortcuts are appended to the built-in ones. Labels can be plain text or locale keys.

## Behaviour

- Responses are rendered at most once per animation frame while streaming.
- <kbd>Esc</kbd> stops generation and closes the menu.
- The conversation is kept while the menu is open, so follow-up prompts refine the previous answer.

# Collaboration

Source: /guide/collaboration

> Real-time collaborative editing with Y.js, remote carets and a presence list.

Collaboration is shipped as a separate entry point, `vue-echo-editor/collaboration`, so apps that don't use it never install or download Y.js.

### Install the peer dependencies

```bash
pnpm add yjs y-websocket @tiptap/y-tiptap @tiptap/extension-collaboration @tiptap/extension-collaboration-caret
```

Any Y.js provider works: [`y-websocket`](https://github.com/yjs/y-websocket), [Hocuspocus](https://tiptap.dev/docs/hocuspocus), `y-webrtc`, `y-indexeddb` or Tiptap Cloud.

### Create the document and provider

```ts
import * as Y from 'yjs'
import { WebsocketProvider } from 'y-websocket'

const doc = new Y.Doc()
const provider = new WebsocketProvider('wss://your-server.example', 'document-42', doc)
```

### Register `CollaborationKit`

```vue [CollaborativeEditor.vue]
<script setup lang="ts">
import { onBeforeUnmount } from 'vue'
import * as Y from 'yjs'
import { WebsocketProvider } from 'y-websocket'
import { EchoEditor, BaseKit, Heading, Bold, Italic, Link, BulletList } from 'vue-echo-editor'
import { CollaborationKit, CollaborationUsers, getUserColor } from 'vue-echo-editor/collaboration'

const props = defineProps<{ room: string; userName: string }>()

const doc = new Y.Doc()
const provider = new WebsocketProvider('wss://your-server.example', props.room, doc)

const extensions = [
  // ⚠️ No `History` — Y.js ships its own collaborative undo manager
  BaseKit,
  CollaborationKit.configure({
    document: doc,
    provider,
    user: { name: props.userName, color: getUserColor(props.userName) },
  }),
  Heading,
  Bold,
  Italic,
  Link,
  BulletList,
]

onBeforeUnmount(() => {
  provider.destroy()
  doc.destroy()
})
</script>

<template>
  <CollaborationUsers :provider="provider" />
  <EchoEditor :extensions="extensions" />
</template>
```

> With collaboration the Y.js document is the source of truth: `v-model` still **emits** updates, but incoming `modelValue` changes are ignored. Load initial content on the server (or into the Y.Doc) instead.
## CollaborationKit options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `document` | `Y.Doc` | — | **Required.** The shared document. |
| `provider` | provider | `null` | Enables remote carets and presence (needs an `awareness` instance). |
| `user` | `{ name, color, avatar? } \| false` | `false` | The local user shown to others. |
| `field` | `string` | `'default'` | Name of the `Y.XmlFragment` in the document. |
| `undoRedo` | `boolean` | `true` | Show undo / redo buttons backed by the Y.js undo manager. |
| `collaboration` | object | `{}` | Extra options for Tiptap's `Collaboration`. |
| `caret` | object | `{}` | Extra options for `CollaborationCaret` (custom caret rendering …). |

## Presence

`<CollaborationUsers :provider :max="5" />` renders an avatar stack of connected users. Build your own UI with the composable:

```ts
import { useCollaborationUsers } from 'vue-echo-editor/collaboration'

const { users } = useCollaborationUsers(provider)
// users.value → [{ clientId, name, color, avatar?, isSelf }]
```

## Offline support

Combine a network provider with `y-indexeddb` to keep working offline and sync when the connection returns:

```ts
import { IndexeddbPersistence } from 'y-indexeddb'

new IndexeddbPersistence('document-42', doc)
```

## Try it without a server

The [examples app](https://github.com/kemboi22/vue-echo-editor/tree/main/examples/demos/CollaborationDemo.vue) links two in-memory Y.js documents so you can see two editors syncing live on one page.

# Internationalization

Source: /guide/i18n

> 11 built-in languages, lazy loading, RTL and custom translations.

## Built-in languages

| Code | Language | Direction |
| --- | --- | --- |
| `en` | English | LTR |
| `zhHans` | 简体中文 | LTR |
| `es` | Español | LTR |
| `fr` | Français | LTR |
| `de` | Deutsch | LTR |
| `pt` | Português | LTR |
| `ru` | Русский | LTR |
| `ja` | 日本語 | LTR |
| `ko` | 한국어 | LTR |
| `ar` | العربية | **RTL** |
| `hi` | हिन्दी | LTR |

English and Chinese are bundled; the others are separate chunks downloaded the first time you switch to them.

## Switch language

```ts
import { locale } from 'vue-echo-editor'

await locale.setLang('fr')
```

`setLang` is async because it may fetch the language chunk. All editors on the page update immediately. For RTL languages the editor sets `dir="rtl"` on its root element.

Build a picker with `supportedLocales`:

```vue
<script setup lang="ts">
import { locale, supportedLocales, useLocale } from 'vue-echo-editor'

const { lang } = useLocale()
</script>

<template>
  <select :value="lang" @change="locale.setLang(($event.target as HTMLSelectElement).value)">
    <option v-for="l in supportedLocales" :key="l.code" :value="l.code">{{ l.nativeName }}</option>
  </select>
</template>
```

## Override or add translations

Missing keys fall back to English, so you only need to provide what you change:

```ts
import { locale } from 'vue-echo-editor'

// Tweak a few labels
locale.extendMessage('en', { 'editor.bold.tooltip': 'Strong' })

// Add a whole new language
locale.setMessage('sw', {
  'editor.bold.tooltip': 'Herufi nzito',
  'editor.italic.tooltip': 'Italiki',
  // …
})
await locale.setLang('sw')
```

The full list of keys is in [`src/locales/locales/en.ts`](https://github.com/kemboi22/vue-echo-editor/blob/main/src/locales/locales/en.ts). Plugins can ship their own translations with the [`locales` option](/api/plugins).

## Using translations in your UI

```ts
import { useLocale } from 'vue-echo-editor'

const { t, lang, direction } = useLocale()
t.value('editor.bold.tooltip')                 // → "Bold"
t.value('my.greeting', { name: 'Ada' })        // "Hello {name}" → "Hello Ada"
```

# Theming

Source: /guide/theming

> Accent colours, border radius, dark mode and CSS customisation.

Echo Editor uses shadcn-vue design tokens (CSS variables) and Tailwind CSS 4 — but its stylesheet is **fully isolated**: every rule is confined to editor elements, so it never restyles your app, even if your app also uses Tailwind or shadcn-vue.

## Props

```vue
<EchoEditor :extensions="extensions" theme="violet" :radius="0.75" :dark="isDark" />
```

- `theme` — `zinc` (default), `slate`, `stone`, `gray`, `neutral`, `red`, `rose`, `orange`, `green`, `blue`, `yellow`, `violet`
- `radius` — `0`, `0.25`, `0.5`, `0.75`, `1` (rem)
- `dark` — `true` / `false`; omit to follow the system preference

## Built-in pickers

```vue
<script setup lang="ts">
import { ThemeToggle, ThemePicker } from 'vue-echo-editor'
</script>

<template>
  <ThemeToggle />  <!-- light / dark -->
  <ThemePicker />  <!-- colour + radius popover -->
</template>
```

## useTheme

```ts
import { useTheme } from 'vue-echo-editor'

const { theme, borderRadius, isDark, setTheme, setBorderRadius, toggleTheme } = useTheme()
setTheme('blue')
```

The state is shared by every editor on the page, persisted in `localStorage`, and safe to call during SSR.

## Custom CSS

Override tokens or target the content element:

```css
.echo-editor {
  --primary: oklch(0.55 0.2 260);
  --radius: 0.375rem;
}

.echo-editor .EchoContentView {
  font-family: 'Inter', sans-serif;
  font-size: 1.0625rem;
  line-height: 1.75;
}

.echo-editor .EchoContentView h1 {
  letter-spacing: -0.02em;
}
```

## Style isolation

At build time every selector in `vue-echo-editor/style.css` is wrapped in a zero-specificity `:where(.echo-editor-ui, .echo-editor-ui *)` guard, and design tokens are defined on `.echo-editor-ui` instead of `:root`. The class is present on the editor root and on everything it portals to `<body>` (menus, popovers, dialogs, toasts, the slash menu).

- No global preflight, utilities or `:root` variables leak into your app.
- Specificity is unchanged, so your overrides above keep working.
- To render stored content outside the editor with editor typography, add both classes: `<div class="echo-editor echo-editor-ui"><div class="EchoContentView" v-html="html" /></div>`.

Useful selectors: `.echo-editor` (root), `.echo-editor-focus` (root while focused), `.EchoContentView` (content), `.echo-toolbar` (toolbar), `.echo-action-button` (toolbar buttons), `.collaboration-carets__caret` / `__label` (remote carets).

# Accessibility

Source: /guide/accessibility

> Keyboard navigation, screen readers, reduced motion and touch support.

Echo Editor aims to meet WCAG 2.2 AA out of the box.

## Keyboard

| Keys | Action |
| --- | --- |
| <kbd>Tab</kbd> | Move focus into / out of the toolbar |
| <kbd>←</kbd> <kbd>→</kbd> | Move between toolbar controls |
| <kbd>Home</kbd> <kbd>End</kbd> | First / last toolbar control |
| <kbd>Esc</kbd> | Close menus, dialogs, find & replace, the AI menu |
| <kbd>Mod</kbd> + <kbd>B</kbd> / <kbd>I</kbd> / <kbd>U</kbd> | Bold / italic / underline |
| <kbd>Mod</kbd> + <kbd>Z</kbd>, <kbd>Mod</kbd> + <kbd>Shift</kbd> + <kbd>Z</kbd> | Undo / redo |
| <kbd>Mod</kbd> + <kbd>F</kbd> | Find & replace |
| <kbd>Mod</kbd> + <kbd>P</kbd> | Print |
| <kbd>F11</kbd> | Fullscreen |
| <kbd>/</kbd> | Slash menu (start of an empty line) |

Shortcuts are exposed to assistive technology through `aria-keyshortcuts`.

## Screen readers

- The editable area is a labelled `role="textbox"` with `aria-multiline`. Set a meaningful name with the `label` prop.
- The toolbar and bubble menus are `role="toolbar"` regions with names; every control has an accessible name, and toggles expose `aria-pressed`.
- Popover buttons expose `aria-haspopup` / `aria-expanded`; dialogs trap focus and restore it on close.
- Reaching the character limit is announced through a live region. Use `announce()` for your own messages:

```ts
import { announce } from 'vue-echo-editor'

announce('Document saved')
announce('Upload failed', 'assertive')
```

## Motion & touch

- `prefers-reduced-motion: reduce` disables editor animations and smooth scrolling.
- On coarse pointers, toolbar controls grow to 40 × 40 px, the toolbar scrolls horizontally, and the drag handle is hidden.
- Fullscreen mode respects device safe areas (notches, home indicators).

## RTL

Arabic sets `dir="rtl"` on the editor root; content direction follows the text.

# Performance

Source: /guide/performance

> How Echo Editor stays fast and how to keep your integration fast.

## What the editor does for you

| Technique | Effect |
| --- | --- |
| **Shared dependencies** | Tiptap, ProseMirror, Vue and the UI primitives are dependencies, not bundled. The main entry is ~49 KB gzipped (down from ~437 KB in 0.x) and your app keeps a single copy of Tiptap. |
| **Lazy feature UIs** | Link / table / image / column menus, the AI menu, menubar, dialogs (preview, source code, special characters) and find & replace are separate chunks, downloaded only when their extension is registered or the dialog is first opened. |
| **Lazy syntax highlighting** | `prism-code-editor` and its grammars (~26 KB gzipped) load on the first code block. |
| **Lazy languages** | Only English and Chinese are bundled; other languages are fetched on demand. |
| **Frame-batched toolbar** | Toolbar and bubble-menu state are recomputed at most once per animation frame, only for transactions that change the document, selection or stored marks — not on every reactive tick. |
| **Cheap v-model** | Serialising is throttled (200 ms, flushed on blur), echoes of the emitted value are detected without re-serialising, and deep watchers are avoided. |
| **Batched streaming** | AI responses render once per frame; code blocks write back to the document in batches. |
| **Per-editor state** | No global listeners per component: theme, locale and stores are shared or scoped. |

## Tips for your app

### Create extensions once

```ts
// ✅ module scope or setup scope
const extensions = [BaseKit, Bold, Italic]

// ❌ creates new extension instances on every evaluation
const extensions = computed(() => [BaseKit, Bold, Italic])
```

The extension list is read when the editor is created; to switch sets, remount with a `key`.

### Use `useEditorState` for custom UI

Reading `editor.state` in a `computed` re-runs on every transaction. `useEditorState` evaluates once per frame and only when something relevant changed:

```ts
import { useEditorState } from 'vue-echo-editor'

const isBold = useEditorState(editor, e => e.isActive('bold'))
const words = useEditorState(editor, e => e.storage.characterCount.words())
```

### Prefer JSON for large documents

`getJSON()` is cheaper than `getHTML()`, and JSON round-trips losslessly. Use `output="json"` for very large documents and render HTML on the server when needed.

### Register only what you use

Each extension adds schema, plugins and a toolbar control. The [minimal preset](/getting-started/quick-start) is a good starting point.

### Keep `v-model` handlers light

Don't send every update to the server — debounce saves or save on `blur`:

```ts
import { useDebounceFn } from '@vueuse/core'

const save = useDebounceFn((html: string) => api.save(html), 1000)
```

# Overview

Source: /extensions/overview

> Every built-in extension, what it does and how to configure it.

All extensions are imported from `vue-echo-editor` (collaboration from `vue-echo-editor/collaboration`). They are regular Tiptap extensions, so every [Tiptap option](https://tiptap.dev/docs/editor/extensions/overview) still applies, plus the toolbar options `spacer`, `divider`, `toolbar` and `button`.

## Core

| Extension | Description |
| --- | --- |
| `BaseKit` | **Required.** Document, paragraph, text, placeholder, character count, focus, drop/gap cursor, trailing node, bubble menu. See [configuration](/guide/configuration#configuring-basekit). |
| `History` / `UndoRedo` | Undo and redo. Not needed (and not allowed) with collaboration. |

## Text formatting

| Extension | Shortcut | Notes |
| --- | --- | --- |
| `Bold` | <kbd>Mod</kbd> <kbd>B</kbd> | |
| `Italic` | <kbd>Mod</kbd> <kbd>I</kbd> | |
| `Underline` | <kbd>Mod</kbd> <kbd>U</kbd> | |
| `Strike` | <kbd>Mod</kbd> <kbd>Shift</kbd> <kbd>S</kbd> | |
| `Code` | <kbd>Mod</kbd> <kbd>E</kbd> | Inline code |
| `MoreMark` | | Dropdown with subscript, superscript and inline code |
| `SubAndSuperScript` | <kbd>Mod</kbd> <kbd>.</kbd> / <kbd>Mod</kbd> <kbd>,</kbd> | Separate buttons |
| `Color` | | Text colour picker with recent colours |
| `Highlight` | | Background colour picker |
| `FontFamily` | | `FontFamily.configure({ fontFamilyMap: { Inter: 'Inter, sans-serif', Georgia: 'Georgia, serif' } })` |
| `FontSize` | | Font size dropdown |
| `LineHeight` | | Line height dropdown |
| `TextAlign` | <kbd>Mod</kbd> <kbd>Shift</kbd> <kbd>L/E/R/J</kbd> | `TextAlign.configure({ types: ['heading', 'paragraph', 'image'] })` |
| `Indent` | <kbd>Tab</kbd> / <kbd>Shift</kbd> <kbd>Tab</kbd> | |
| `Clear` | | Remove all formatting |
| `FormatPainter` | | Copy formatting to another selection |
| `Link` | | Link popover + link bubble menu; `Link.configure({ openOnClick: false })` |

## Blocks

| Extension | Notes |
| --- | --- |
| `Heading` | H1–H6 dropdown; `Heading.configure({ levels: [1, 2, 3] })` |
| `BulletList` | Disc, circle and square styles |
| `OrderedList` | Decimal, roman, latin and CJK numbering |
| `TaskList` | `TaskList.configure({ taskItem: { nested: true } })` |
| `Blockquote` | |
| `CodeBlock` | Syntax highlighting (lazy-loaded prism-code-editor), language picker, line numbers, word wrap, tab size |
| `HorizontalRule` | |
| `Table` | Grid picker, table bubble menu, merge/split cells, cell background colour, column resizing |
| `Columns` | Two, three or four column layouts |

## Media

| Extension | Notes |
| --- | --- |
| `Image` | Resize handles, alignment, flip, size presets, image bubble menu |
| `ImageUpload` | `upload(file) => Promise<url>`, `acceptMimes`, `maxSize` — see [uploads](/guide/uploads) |
| `Video` | Embedded video with size presets |
| `VideoUpload` | `upload(files) => Promise<{ src }[]>` |
| `Iframe` | Embed services from a link (YouTube, Figma, CodePen, …) |

## Tools

| Extension | Notes |
| --- | --- |
| `SlashCommand` | "/" command menu — see [slash commands](/extensions/slash-commands) |
| `FindAndReplace` | <kbd>Mod</kbd> <kbd>F</kbd>, regex-safe, case-sensitive option |
| `SourceCode` | Edit HTML source with syntax highlighting and search |
| `Preview` | Read-only preview dialog |
| `Printer` | <kbd>Mod</kbd> <kbd>P</kbd> |
| `Fullscreen` | <kbd>F11</kbd> |
| `SpecialCharacter` | Searchable character picker |
| `ImportWord` | Import `.docx` via your `convert` function |
| `Markdown` | Markdown parsing / serialisation — see [Markdown](/guide/markdown) |
| `Export` | PDF, Markdown, HTML, RTF, text, JSON — see [Export](/guide/export) |

## AI & collaboration

| Extension | Notes |
| --- | --- |
| `AI` | Inline AI menu — see [AI assistant](/guide/ai) |
| `CollaborationKit` | Y.js collaboration — see [Collaboration](/guide/collaboration) |

## Using any Tiptap extension

Any Tiptap 3 extension works — it just won't have a toolbar button unless you add one:

```ts
import { Mention } from '@tiptap/extension-mention'
import { Typography } from '@tiptap/extension-typography'

const extensions = [BaseKit, Bold, Italic, Typography, Mention.configure({ suggestion })]
```

# Custom extensions

Source: /extensions/custom

> Write your own extension with a toolbar button, or extend a built-in one.

An Echo Editor extension is a Tiptap extension whose options include a `button` function. The toolbar calls it to render the control.

## A toolbar button for a custom command

```ts [extensions/Timestamp.ts]
import { Extension } from '@tiptap/core'
import { ActionButton } from 'vue-echo-editor'
import type { GeneralOptions } from 'vue-echo-editor'

declare module '@tiptap/core' {
  interface Commands<ReturnType> {
    timestamp: { insertTimestamp: () => ReturnType }
  }
}

export interface TimestampOptions extends GeneralOptions<TimestampOptions> {
  format: Intl.DateTimeFormatOptions
}

export const Timestamp = Extension.create<TimestampOptions>({
  name: 'timestamp',

  addOptions() {
    return {
      ...(this.parent?.() as TimestampOptions),
      format: { dateStyle: 'medium', timeStyle: 'short' },
      button: ({ editor, extension, t }) => ({
        component: ActionButton,
        componentProps: {
          icon: 'Hash',
          tooltip: 'Insert timestamp',
          action: () => editor.chain().focus().insertTimestamp().run(),
          disabled: !editor.isEditable,
        },
      }),
    }
  },

  addCommands() {
    return {
      insertTimestamp:
        () =>
        ({ commands }) =>
          commands.insertContent(new Intl.DateTimeFormat(undefined, this.options.format).format(new Date())),
    }
  },

  addKeyboardShortcuts() {
    return { 'Mod-Shift-t': () => this.editor.commands.insertTimestamp() }
  },
})
```

## The button contract

`button({ editor, extension, t })` returns one item (or an array of items):

```ts
interface ButtonViewReturn {
  component: Component          // usually ActionButton
  componentProps: {
    action?: (value?: any) => void
    isActive?: () => boolean
    icon?: IconName             // name from the built-in Lucide icon map
    tooltip?: string
    shortcutKeys?: string[]     // e.g. ['mod', 'shift', 'T']
    disabled?: boolean
    [key: string]: any          // forwarded to your component
  }
  componentSlots?: Record<string, () => any>
}
```

The function runs at most once per animation frame, so reading `editor.isActive()` / `editor.can()` inside it is cheap.
> Your own component receives `editor` and `disabled` props in addition to `componentProps`.
## Extending a built-in extension

```ts
import { Heading } from 'vue-echo-editor'

export const CompactHeading = Heading.extend({
  addOptions() {
    return { ...this.parent?.(), levels: [2, 3] }
  },
  addKeyboardShortcuts() {
    return {
      ...this.parent?.(),
      'Mod-Alt-0': () => this.editor.commands.setParagraph(),
    }
  },
})
```

## Node views with Vue

Use Tiptap's `VueNodeViewRenderer` for interactive blocks. Remember that in Tiptap 3 `getPos()` can return `undefined`:

```vue
<script setup lang="ts">
import { NodeViewWrapper, nodeViewProps } from '@tiptap/vue-3'

const props = defineProps(nodeViewProps)

function select() {
  const pos = props.getPos()
  if (typeof pos === 'number') props.editor.commands.setNodeSelection(pos)
}
</script>

<template>
  <NodeViewWrapper @click="select">…</NodeViewWrapper>
</template>
```

To package extensions, buttons, slash commands and translations together, use [`definePlugin`](/api/plugins).

# Slash commands

Source: /extensions/slash-commands

> Configure the "/" command menu and add your own commands.

`SlashCommand` opens a searchable command menu when you type <kbd>/</kbd> at the start of an empty paragraph (also inside columns). Use <kbd>↑</kbd> <kbd>↓</kbd> to navigate, <kbd>Enter</kbd> to run and <kbd>Esc</kbd> to close.

## Preset groups

| Group | Commands (when the extension is registered) |
| --- | --- |
| `format` | Paragraph, headings 1–3, bullet and numbered lists, code block, blockquote, horizontal rule, link |
| `insert` | Image, table, video, task list, two / three / four columns |
| `others` | Embed services (requires `Iframe`) |

## Customising

```ts
SlashCommand.configure({
  getCommandGroups: ({ presetGroups, editor, lang }) => {
    // Hide a group
    const groups = presetGroups.filter(group => group.name !== 'others')

    // Add commands to an existing group
    groups.find(group => group.name === 'insert')?.commands.push({
      name: 'callout',
      label: lang === 'fr' ? 'Encadré' : 'Callout',
      aliases: ['note', 'info'],
      iconName: 'Quote',
      description: 'Highlighted note',
      action: ({ editor, range }) =>
        editor.chain().focus().deleteRange(range).insertContent('<blockquote><p>💡 </p></blockquote>').run(),
    })

    return groups
  },
})
```

### Command shape

```ts
interface Command {
  name: string
  label: string
  description?: string
  aliases?: string[]                         // extra search terms
  iconName?: IconName                        // built-in icon
  iconUrl?: string                           // or an image
  shouldBeHidden?: (editor: Editor) => boolean
  action: ({ editor, range }) => void        // delete `range` to remove the "/query" text
}
```

Search matches the label and every alias, case-insensitively.

## From plugins

Plugins can add commands without configuring `SlashCommand` — see [`slashCommands`](/api/plugins#slash-commands).

# Editor instance

Source: /api/editor

> Working with the underlying Tiptap editor — commands, content and events.

`<EchoEditor>` exposes the [Tiptap `Editor`](https://tiptap.dev/docs/editor/api/editor). Grab it from the `create` event or a template ref (see [Configuration](/guide/configuration#exposed-instance) for all props and events).

## Content

```ts
editor.getHTML()
editor.getJSON()
editor.getText()
editor.getMarkdown()                      // with the Markdown extension
editor.isEmpty

editor.commands.setContent('<p>New</p>')
editor.commands.setContent(json, { emitUpdate: false })
editor.commands.setContent('# Title', { contentType: 'markdown' })
editor.commands.clearContent()
```

## Commands

Commands can be chained; `focus()` returns focus to the editor after a toolbar click:

```ts
editor.chain().focus().toggleBold().toggleItalic().run()
editor.can().toggleBold()                 // dry run — would it work?
```

Commands contributed by Echo Editor extensions:

| Command | Extension |
| --- | --- |
| `setFullscreen()` | `Fullscreen` |
| `togglePreview()` | `Preview` |
| `toggleSourceCode()` | `SourceCode` |
| `toggleSpecialCharacter()`, `insertSpecialCharacter(char)` | `SpecialCharacter` |
| `setSearchTerm()`, `setReplaceTerm()`, `nextSearchResult()`, `replace()`, `replaceAll()` … | `FindAndReplace` |
| `exportDocument(format, filename?)` | `Export` |
| `setImage(attrs)`, `updateImage(attrs)` | `Image` |
| `setVideo(attrs)`, `updateVideo(attrs)` | `Video` |
| `setCodeBlock(attrs?)` | `CodeBlock` |
| `setTableCellBackground(color)`, `unsetTableCellBackground()` | `Table` |
| `setColumns()`, `setThreeColumns()`, `setFourColumns()`, `setLayout(layout)` | `Columns` |
| `setIframe(attrs)` | `Iframe` |
| `indent()`, `outdent()` | `Indent` |
| `setLineHeight(value)` | `LineHeight` |
| `setFontSize(size)`, `unsetFontSize()` | `FontSize` |

Plus every command from the underlying Tiptap extensions (`toggleHeading`, `insertTable`, `setLink`, `setTextAlign`, …).

## Events

```ts
editor.on('update', ({ editor }) => {})
editor.on('selectionUpdate', ({ editor }) => {})
editor.on('transaction', ({ transaction }) => {})
editor.on('focus', ({ event }) => {})
editor.on('blur', ({ event }) => {})
editor.on('destroy', () => {})
```

Always remove listeners you add (`editor.off(...)`) when your component unmounts.

## Reading state in Vue

`editor.state` is reactive, but reading it in a `computed` re-evaluates on **every** transaction. Prefer [`useEditorState`](/api/composables#useeditorstate).

# Composables

Source: /api/composables

> useEditorState, useTheme, useLocale, useTiptapStore and useCollaborationUsers.

## useEditorState

Derive UI state from an editor, re-evaluated **at most once per animation frame** and only for transactions that change the document, selection or stored marks. The selector runs outside Vue's dependency tracking, so it is safe to call `editor.can()` and `editor.isActive()` many times.

```ts
import { useEditorState } from 'vue-echo-editor'

const state = useEditorState(editor, e => ({
  bold: e.isActive('bold'),
  canUndo: e.can().undo(),
  words: e.storage.characterCount.words(),
}), {
  // Re-run when these change too
  sources: [() => props.disabled],
  // Skip updates when nothing changed
  equalityFn: (a, b) => a.bold === b.bold && a.canUndo === b.canUndo && a.words === b.words,
})
```

| Option | Type | Description |
| --- | --- | --- |
| `sources` | `WatchSource[]` | Extra reactive sources that trigger a re-evaluation. |
| `equalityFn` | `(a, b) => boolean` | Keep the previous value when it returns `true`. Defaults to `Object.is`. |

Listeners are removed automatically when the calling component (or effect scope) is disposed.

## useTheme

```ts
const { theme, borderRadius, isDark, themes, borderRadiusOptions, setTheme, setBorderRadius, toggleTheme } = useTheme()
```

Shared across all editors, persisted to `localStorage`, SSR-safe. See [Theming](/guide/theming).

## useLocale

```ts
const { lang, t, direction } = useLocale()

t.value('editor.bold.tooltip')          // translated string
t.value('greeting', { name: 'Ada' })    // with {placeholders}
direction.value                          // 'ltr' | 'rtl'
```

`lang` is read-only — change it with `await locale.setLang(code)`. See [Internationalization](/guide/i18n).

## useTiptapStore

UI state of one editor (fullscreen, preview, source code, find & replace, AI menu, spell check, printer, disabled):

```ts
import { useTiptapStore } from 'vue-echo-editor'

const store = useTiptapStore(editor)
store.toggleFullscreen()
store.state.isFullscreen
```

Inside components rendered by `<EchoEditor>` (custom buttons, node views) the editor argument can be omitted — the store is injected.

## useRovingToolbar

Arrow-key navigation for your own toolbars:

```vue
<script setup lang="ts">
import { useRovingToolbar } from 'vue-echo-editor'

const { toolbarRef, onKeydown } = useRovingToolbar()
</script>

<template>
  <div ref="toolbarRef" role="toolbar" aria-label="Formatting" @keydown="onKeydown">
    <button>Bold</button>
    <button>Italic</button>
  </div>
</template>
```

## useCollaborationUsers

From `vue-echo-editor/collaboration`:

```ts
const { users } = useCollaborationUsers(provider)   // provider can be a ref or getter
// [{ clientId, name, color, avatar?, isSelf }]
```

## useEditor

Tiptap's own `useEditor` is re-exported for building a completely custom editor UI with Echo Editor extensions.

# Plugins

Source: /api/plugins

> Package extensions, toolbar buttons, slash commands and translations with definePlugin().

`definePlugin()` is the recommended way to share functionality — in your app or as an npm package. The result is a normal Tiptap extension you add to `extensions`.

```ts [plugins/timestamp.ts]
import { ActionButton, definePlugin } from 'vue-echo-editor'

export const Timestamp = definePlugin({
  name: 'timestamp',

  // Translations — missing keys fall back to English
  locales: {
    en: { 'timestamp.insert': 'Insert timestamp' },
    fr: { 'timestamp.insert': "Insérer l'horodatage" },
  },

  // Toolbar button (same contract as built-in extensions)
  toolbar: ({ editor, t }) => ({
    component: ActionButton,
    componentProps: {
      icon: 'Hash',
      tooltip: t('timestamp.insert'),
      action: () => editor.chain().focus().insertContent(new Date().toLocaleString()).run(),
    },
  }),

  // Slash menu entries
  slashCommands: [
    {
      name: 'insert', // extend a preset group…
      commands: [
        {
          name: 'timestamp',
          label: 'Timestamp',
          aliases: ['date', 'now'],
          iconName: 'Hash',
          action: ({ editor, range }) =>
            editor.chain().focus().deleteRange(range).insertContent(new Date().toLocaleString()).run(),
        },
      ],
    },
  ],

  // Runs when the editor is created; return a cleanup function
  setup({ editor }) {
    const onBlur = () => console.log('saved at', Date.now())
    editor.on('blur', onBlur)
    return () => editor.off('blur', onBlur)
  },
})
```

```ts
const extensions = [BaseKit, Bold, SlashCommand, Timestamp]
```

## Definition

| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | **Required.** Unique name (also the extension name). |
| `defaultOptions` | `object` | Options available as `options` in the callbacks; override with `plugin.configure({ pluginOptions })`. |
| `extensions` | `AnyExtension[] \| (options) => AnyExtension[]` | Tiptap extensions the plugin brings along. |
| `toolbar` | `ButtonView` | Toolbar button(s). |
| `slashCommands` | `PluginSlashGroup[] \| (ctx) => PluginSlashGroup[]` | Slash menu contributions. |
| `locales` | `Record<lang, Record<key, string>>` | Translations, registered when the plugin is defined. |
| `setup` | `({ editor, options }) => void \| (() => void)` | Called after the editor is created; the returned function runs on destroy. |

## Options

```ts
const Greeting = definePlugin({
  name: 'greeting',
  defaultOptions: { text: 'Hello' },
  toolbar: ({ editor, extension }) => ({
    component: ActionButton,
    componentProps: {
      icon: 'Sparkles',
      tooltip: 'Greet',
      action: () => editor.commands.insertContent(extension.options.pluginOptions.text),
    },
  }),
})

Greeting.configure({ pluginOptions: { text: 'Karibu' } })
```

## Slash commands

A `PluginSlashGroup` with the `name` of a preset group (`format`, `insert`, `others`) appends commands to it; any other name creates a new group titled `title` (a string or a locale key).

## Publishing a plugin

- Name the package `echo-editor-plugin-*` and add the `echo-editor-plugin` keyword.
- List `vue-echo-editor` and any `@tiptap/*` packages as **peer** dependencies.
- Ship translations for at least English through `locales`.

# Utilities & types

Source: /api/utilities

> Helper functions, components and TypeScript types exported by the package.

## Functions

| Export | Description |
| --- | --- |
| `hasExtension(editor, name)` | Whether an extension (including nested ones) is registered. |
| `announce(message, politeness?)` | Announce a message to screen readers through a shared live region. |
| `printHTML(html, { title })` | Print HTML through a hidden iframe (used by PDF export). |
| `createStandaloneHTML(html, { title, lang })` | Wrap editor HTML into a styled standalone document. |
| `serialize(editor, format, title?)` | Get `{ content, mimeType, extension }` for `html`, `json`, `markdown`, `text` or `rtf`. |
| `exportDocument(editor, format, filename?)` | Serialize and download (or print for `pdf`). |
| `jsonToRTF(json)` | Convert a Tiptap JSON document to RTF. |
| `toPlainText(editor)` | Plain text with blank lines between blocks. |
| `downloadFile(content, filename, mimeType?)` | Trigger a browser download. |
| `getUserColor(name)` | Stable caret colour for a user name (collaboration entry). |

## Components

| Export | Description |
| --- | --- |
| `EchoEditor` | The editor component. |
| `EchoEditorPlugin` | Vue plugin that registers `EchoEditor` globally. |
| `ActionButton` | The toolbar button used by built-in extensions — reuse it for consistent custom buttons. |
| `ThemeToggle`, `ThemePicker` | Dark mode toggle and colour / radius picker. |
| `CollaborationUsers` | Presence avatars (collaboration entry). |

## Types

```ts
import type {
  EchoEditorProps,
  EchoEditorEmits,
  EchoEditorOnChange,
  EditorInstance,        // Tiptap Editor
  JSONContent,
  GeneralOptions,        // spacer / divider / toolbar / button
  ButtonView,
  ButtonViewReturn,
  ButtonViewParams,
  Group,
  Command,               // slash command
  ExportFormat,
  Theme,
  LocaleConfig,
  LocaleMessages,
  EchoEditorPluginDefinition,
  UseEditorStateOptions,
} from 'vue-echo-editor'

import type { CollaborationKitOptions, CollaborationUser, CollaborationProvider } from 'vue-echo-editor/collaboration'
```

Extension option types are exported next to each extension (`HeadingOptions`, `TableOptions`, `ExportOptions`, …).

# llms.txt

Source: /ai/llms-txt

> Machine-readable documentation for LLMs and coding agents.

These docs publish the [llms.txt](https://llmstxt.org) standard files so AI assistants can learn Echo Editor without scraping HTML.

| URL | Contents |
| --- | --- |
| [`/llms.txt`](/llms.txt) | Index of every page with a one-line description, grouped by section, plus the MCP endpoint. |
| [`/llms-full.txt`](/llms-full.txt) | The complete documentation in one Markdown file. |
| `/raw/<path>.md` | Any single page as clean Markdown, e.g. [`/raw/guide/markdown.md`](/raw/guide/markdown.md). |

## Using it

- **Chat assistants** — paste the `/llms-full.txt` URL (or its contents) into the conversation: *"Using https://echo-editor.dev/llms-full.txt, add a Markdown editor to my Vue app."*
- **Cursor / Windsurf** — add `https://echo-editor.dev/llms-full.txt` as a docs source (`@Docs → Add new doc`).
- **Claude Code / agents** — point them at `/llms.txt`; they can follow the links to the raw Markdown pages. Better still, connect the [MCP server](/ai/mcp).

## How it's generated

The files are built from the same Markdown that powers this site, using [`nuxt-llms`](https://github.com/nuxt-content/nuxt-llms) with a small Nitro plugin that walks the `content/` directory. They are prerendered at build time, so they are always in sync with the docs.

# MCP server

Source: /ai/mcp

> Connect Claude, Cursor, VS Code and other agents to the Echo Editor docs via the Model Context Protocol.

This site runs a remote [Model Context Protocol](https://modelcontextprotocol.io) server at **`/mcp`** (Streamable HTTP). Coding agents can search and read the documentation, list extensions and generate setup code — so they write correct Echo Editor code instead of guessing.

## Connect

  ```bash
  claude mcp add --transport http echo-editor https://echo-editor.dev/mcp
  ```

  ```json [.cursor/mcp.json]
  {
    "mcpServers": {
      "echo-editor": { "url": "https://echo-editor.dev/mcp" }
    }
  }
  ```

  ```json [.vscode/mcp.json]
  {
    "servers": {
      "echo-editor": { "type": "http", "url": "https://echo-editor.dev/mcp" }
    }
  }
  ```

  ```bash
  npx add-mcp https://echo-editor.dev/mcp
  ```

Running the docs locally (`pnpm docs:dev`)? Use `http://localhost:3000/mcp`.

## Tools

| Tool | Description |
| --- | --- |
| `search_docs` | Ranked full-text search across all pages, returning excerpts. |
| `get_doc` | Read a page as Markdown by path (e.g. `/guide/collaboration`). |
| `list_docs` | Every page with its path and description, grouped by section. |
| `list_extensions` | The extension catalogue with descriptions and configuration examples, filterable by category. |
| `get_setup_code` | Install commands and a ready-to-paste Vue or Nuxt component for a preset (`minimal`, `blog`, `full`), extra extensions, output format and optional collaboration. |

## Resources

Every page is exposed as a resource at `docs://<path>` (e.g. `docs://guide/markdown`), so clients that support resources can attach pages to the context directly.

## Prompts

| Prompt | Arguments | Description |
| --- | --- | --- |
| `integrate_echo_editor` | `framework` (`vue` \| `nuxt`), `requirements` | Walks the agent through picking extensions, generating setup code and checking the relevant guides. |

## Example

> *"Add a collaborative Markdown editor with image uploads to my Nuxt app."*

The agent calls `list_extensions`, then `get_setup_code` with `framework: "nuxt"`, `output: "markdown"`, `extra: ["ImageUpload"]` and `collaboration: true`, and reads `/guide/uploads` with `get_doc` — producing a working component on the first try.

## Self-hosting

The server lives in the docs app (`docs/server/mcp`) and is built with [`@nuxtjs/mcp-toolkit`](https://mcp-toolkit.nuxt.dev). Deploy the docs anywhere Nitro runs (Vercel, Netlify, Cloudflare, Node) and the endpoint comes with it.