` markup are read back as a `line` divider, so existing documents open unchanged. ## Options ### variants Type: `{ value: string; label?: string; editable?: boolean }[]`\ Default: the nine built-in variants, `text` editable The styles offered, in menu order. Remove entries to offer fewer; add your own `value` and style `.divider--` in your CSS. `editable` shows the label input. `label` overrides the menu text (built-in values are translated). ```ts Divider.configure({ variants: [ { value: 'line' }, { value: 'text', editable: true }, { value: 'wave', label: 'Wave' }, // styled by your CSS ], }); ``` ### defaultVariant Type: `string`\ Default: `'line'` Inserted by the toolbar button, the slash command and the shortcut. ### renderDivider Type: `(attrs: { variant: string; label: string | null }) => DOMOutputSpec`\ Default: the markup above Replaces the saved HTML. Pair it with `parseRules` so the same markup reads back: ```ts Divider.configure({ renderDivider: ({ variant, label }) => [ 'hr', { class: `sep sep-${variant}`, 'data-label': label ?? '' }, ], parseRules: [ { tag: 'hr.sep', getAttrs: (el) => ({ variant: (el as HTMLElement).className.replace(/.*sep-(\S+).*/, '$1'), label: (el as HTMLElement).getAttribute('data-label') || null, }), }, ], }); ``` ### parseRules Type: `ParseRule[]`\ Default: `[]` Extra rules tried before the built-in ones. ### shortcutKeys Type: `string[]`\ Default: `['mod', 'alt', 'S']` Shortcut labels shown by the controls. See [keyboard shortcut configuration](/guide/toolbar#keyboard-shortcuts) to change actual key bindings. --- # Drawer Create freehand drawings and insert them into the document. ## Setup Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`. ::: code-group ```tsx [React] 'use client'; import { EditorContent, useEditor } from '@tiptap/react'; import { Document } from '@tiptap/extension-document'; import { Paragraph } from '@tiptap/extension-paragraph'; import { Text } from '@tiptap/extension-text'; import { RichTextProvider, Drawer, RichTextDrawer, RichTextBubbleDrawer, } from 'ai-sparkwrite-editor'; import 'ai-sparkwrite-editor/style.css'; import 'easydrawer/styles.css'; const extensions = [Document, Paragraph, Text, Drawer]; export default function DrawerExample() { const editor = useEditor({ extensions, content: '

Try this feature here.

', immediatelyRender: false, }); if (!editor) return null; return ( ); } ``` ::: ::: warning React only This feature's interactive UI depends on React libraries; the Vue layer does not include it yet. See [Frameworks](/guide/frameworks) for what the Vue entry covers. ::: ## How to use Load `easydrawer/styles.css` alongside the editor stylesheet. Open the drawing dialog, draw, and apply the result. You can provide an `upload` callback resolving to a durable URL to store the generated SVG remotely. Install `easydrawer` directly if needed to resolve its CSS import. ## Loading behavior The drawing canvas loads when a create or edit dialog opens. The first open may show a loading placeholder, and a failed module load offers a retry action. Keep the stylesheet import above so the canvas is styled when it becomes available. --- # Emoji Insert emoji using a picker or suggestions. ## Setup Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`. ::: code-group ```tsx [React] 'use client'; import { EditorContent, useEditor } from '@tiptap/react'; import { Document } from '@tiptap/extension-document'; import { Paragraph } from '@tiptap/extension-paragraph'; import { Text } from '@tiptap/extension-text'; import { RichTextProvider, Emoji, RichTextEmoji } from 'ai-sparkwrite-editor'; import 'ai-sparkwrite-editor/style.css'; const extensions = [Document, Paragraph, Text, Emoji]; export default function EmojiExample() { const editor = useEditor({ extensions, content: '

Try this feature here.

', immediatelyRender: false, }); if (!editor) return null; return ( ); } ``` ::: ::: warning React only This feature's interactive UI depends on React libraries; the Vue layer does not include it yet. See [Frameworks](/guide/frameworks) for what the Vue entry covers. ::: ## How to use Open the toolbar picker and choose an emoji. The extension supplies its emoji data and suggestion UI; no upload endpoint or separate toolbar provider is needed. - Copy Emoji List here: https://github.com/ludejun/ai-sparkwrite-editor-demo/blob/master/src/components/Editor/emojis.ts ## Loading behavior The toolbar picker UI loads when the popover first opens. The extension still includes its full emoji dictionary for schema behavior, shortcodes, and document round trips; deferring the picker does not remove that dictionary. If you provide a separate suggestion dataset, you can dynamically import it from an asynchronous `suggestion.items` callback. --- # Excalidraw Create and insert Excalidraw drawings. ## Setup Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`. ::: code-group ```tsx [React] 'use client'; import { EditorContent, useEditor } from '@tiptap/react'; import { Document } from '@tiptap/extension-document'; import { Paragraph } from '@tiptap/extension-paragraph'; import { Text } from '@tiptap/extension-text'; import { RichTextProvider, Excalidraw, RichTextExcalidraw, RichTextBubbleExcalidraw, } from 'ai-sparkwrite-editor'; import 'ai-sparkwrite-editor/style.css'; import '@excalidraw/excalidraw/index.css'; const extensions = [Document, Paragraph, Text, Excalidraw]; export default function ExcalidrawExample() { const editor = useEditor({ extensions, content: '

Try this feature here.

', immediatelyRender: false, }); if (!editor) return null; return ( ); } ``` ::: ::: warning React only This feature's interactive UI depends on React libraries; the Vue layer does not include it yet. See [Frameworks](/guide/frameworks) for what the Vue entry covers. ::: ## How to use Load `@excalidraw/excalidraw/index.css` alongside the editor stylesheet. Open the toolbar dialog, create a drawing, and apply it. Mount `RichTextBubbleExcalidraw` for contextual actions. Install `@excalidraw/excalidraw` directly if needed to resolve its CSS import. --- # Export Markdown Download the current document as a `.md` file, or get the markdown string to send to your backend. ## Setup Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`. ::: code-group ```tsx [React] 'use client'; import { EditorContent, useEditor } from '@tiptap/react'; import { Document } from '@tiptap/extension-document'; import { Paragraph } from '@tiptap/extension-paragraph'; import { Text } from '@tiptap/extension-text'; import { RichTextProvider, Bold, Heading, ExportMarkdown, RichTextExportMarkdown, } from 'ai-sparkwrite-editor'; import 'ai-sparkwrite-editor/style.css'; const extensions = [Document, Paragraph, Text, Bold, Heading, ExportMarkdown]; export default function ExportMarkdownExample() { const editor = useEditor({ extensions, content: '

Title

Try this feature here.

', immediatelyRender: false, }); if (!editor) return null; return ( ); } ``` ```vue [Vue] ``` ::: ::: tip Vue Not in the Vue layer yet: `RichTextExportMarkdown` — run the corresponding command from your own control, or see [Frameworks](/guide/frameworks). ::: ## How to use Press the toolbar button to download the document as markdown. The serializer (`@tiptap/markdown`) is loaded on demand the first time it is used, so it does not affect the initial bundle. Every node is serialized: | Content | Output | | ------------------------------------------------------------------------- | ------------------------------------------ | | Headings, paragraphs, bold, italic, strike, code, links, images, lists | Standard / GFM markdown | | Task lists, tables, blockquotes, code blocks, horizontal rules, highlight | GFM markdown | | Details (toggle) | `

…

` | | Callout | GitHub alert (`> [!NOTE]`, `> [!TIP]`, …) | | Table of contents block | `[TOC]` | | Katex | `$formula$` | | Attachment | `[file name](url)` | | Twitter | `[url](url)` | | Columns | Column contents one after another | | Subscript / superscript | `_{` / `^{` |
| Video, iframe, mermaid, excalidraw, drawer and other custom nodes | Rendered as HTML so nothing is lost |

Text styles such as color, font size, font family, alignment and line height are dropped, as markdown has no equivalent.

## Use from code

```ts
import { getMarkdown } from 'ai-sparkwrite-editor';

// download
editor.chain().focus().exportToMarkdown({ fileName: 'notes.md' }).run();

// get the string (e.g. to save on your server)
const markdown = await getMarkdown(editor);
```

## Options

```ts
ExportMarkdown.configure({
// name of the downloaded file
fileName: 'richtext-export-document.md',
// indentation for nested lists
indentation: { style: 'space', size: 2 },
});
```

---

# Export PDF

Open the browser’s print flow for the editor content.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, ExportPdf, RichTextExportPdf } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, ExportPdf];

export default function ExportPdfExample() {
const editor = useEditor({
extensions,
content: 'Try this feature here.',
immediatelyRender: false,
});

if (!editor) return null;

return (

);
}
```

```vue [Vue]

```

:::

::: tip Vue
Not in the Vue layer yet: `RichTextExportPdf` — run the corresponding command from your own control, or see [Frameworks](/guide/frameworks).
:::

## How to use

Click the toolbar button, then choose the browser’s PDF destination if available. This uses browser printing rather than returning a PDF Blob. Configure paper size and margins below, and review the print preview because the browser controls the final output.

---

## Options

### paperSize

Type: `PaperSize`

Default: `'Letter'`

Specifies the size of the paper used when exporting to PDF.

Supported values:

```ts
type PaperSize = 'Legal' | 'Letter' | 'Tabloid' | 'A0' | 'A1' | 'A2' | 'A3' | 'A4' | 'A5';
```

### margins

Type:

```ts
{
top: PageMargin;
right: PageMargin;
bottom: PageMargin;
left: PageMargin;
}
```

Default:

```ts
{
top: '0.4in',
right: '0.4in',
bottom: '0.4in',
left: '0.4in'
}
```

Controls the page margins on all four sides. Values can be provided in inches (`in`), centimeters (`cm`), millimeters (`mm`), or points (`pt`).

Supported values:

```ts
type PageMargin =
// Inches
| '0in'
| '0.25in'
| '0.4in'
| '0.5in'
| '0.75in'
| '1in'
| '1.25in'
| '1.5in'
| '1.75in'
| '2in'
// Centimeters
| '0cm'
| '0.5cm'
| '1cm'
| '1.5cm'
| '2cm'
| '2.5cm'
| '3cm'
| '4cm'
| '5cm'
// Millimeters
| '0mm'
| '5mm'
| '10mm'
| '15mm'
| '20mm'
| '25mm'
| '30mm'
| '40mm'
| '50mm'
// Points
| '0pt'
| '18pt'
| '36pt'
| '54pt'
| '72pt'
| '90pt'
| '108pt'
| '144pt';
```

Example usage:

```ts
import { ExportPdf } from 'ai-sparkwrite-editor';

ExportPdf.configure({
paperSize: 'A4',
margins: {
top: '1in',
right: '0.4in',
bottom: '1in',
left: '0.4in',
},
});
```

---

# Export Word

Download the current document as a `.docx` file.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, ExportWord, RichTextExportWord } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, ExportWord];

export default function ExportWordExample() {
const editor = useEditor({
extensions,
content: 'Try this feature here.',
immediatelyRender: false,
});

if (!editor) return null;

return (

);
}
```

```vue [Vue]

```

:::

::: tip Vue
Not in the Vue layer yet: `RichTextExportWord` — run the corresponding command from your own control, or see [Frameworks](/guide/frameworks).
:::

## How to use

Click the toolbar button or call `editor.commands.exportToWord(editor.state.doc)`. The download uses `richtext-export-document.docx`. The current serializer excludes images and does not define mappings for every custom node or mark; test your document’s feature set before relying on Word export.

## Loading behavior

The Word serializer loads when export is requested. `exportToWord` returns a Tiptap command boolean immediately; it does not return a promise indicating that the download has finished. Serialization and download happen asynchronously, and failures are logged to the console. `editor.can().exportToWord(editor.state.doc)` does not load the serializer or start a download.

---

# Font Family

Choose the font family used by selected text.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). Install `@tiptap/extension-text-style` at the same version as your other Tiptap packages. The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, FontFamily, RichTextFontFamily } from 'ai-sparkwrite-editor';
import { TextStyle } from '@tiptap/extension-text-style';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, TextStyle, FontFamily];

export default function FontFamilyExample() {
const editor = useEditor({
extensions,
content: 'Try this feature here.',
immediatelyRender: false,
});

if (!editor) return null;

return (

);
}
```

```vue [Vue]

```

:::

::: tip Vue
Not in the Vue layer yet: `RichTextFontFamily` — run the corresponding command from your own control, or see [Frameworks](/guide/frameworks).
:::

## How to use

Register `TextStyle`. `fontFamilyList` controls the choices in the dropdown, but does not download fonts. Load web fonts in your application CSS, or choose fonts available on the reader’s device.

A plain string is used as both the label and the CSS value. A `{ name, value }`
entry separates them, which is what a cross-platform stack needs: the menu can
stay readable while the value lists one face per platform.

## Non-Latin scripts

Arial, Georgia, Times and the rest of the Latin defaults carry no Han,
Devanagari or Bengali glyphs, so applying one to Chinese or Hindi text changes
nothing visible — the browser substitutes a default face. The default list
therefore ends with the entries in `SCRIPT_FONT_FAMILY_LIST`:

| Script | Entries |
| ---------- | -------------------------------- |
| Chinese | 微软雅黑, 苹方, 黑体, 宋体, 楷体 |
| Japanese | ゴシック体, 明朝体 |
| Korean | 맑은 고딕 |
| Devanagari | देवनागरी |
| Bengali | বাংলা |

Each is named after the font readers know and resolves to a stack, so the
choice lands on that face where it exists and on the closest equivalent
elsewhere — 微软雅黑 gives Microsoft YaHei on Windows and PingFang SC on macOS,
the substitution every word processor has always done.

They are all system fonts by design: a webfont covering Han runs to several
megabytes even subset. To ship one anyway, load it in your CSS and add it to
`fontFamilyList` yourself.

### When they appear

Listing every script at all times buries the Latin fonts for readers who will
never use them. The picker shows a script's entries when **either** the
interface language uses that script **or** the document already contains it —
the document is sampled when the menu opens, so pasting Chinese into an
English-language editor brings the Chinese fonts back straight away. Entries
you add through `fontFamilyList` are never filtered.

The editor's own body text is unaffected by this list — it inherits the font of
the page it is embedded in. `system-ui` already falls back to a sensible CJK
face on every platform, so only an explicit choice needs these entries.

## Configuration

```ts
import { FontFamily } from 'ai-sparkwrite-editor';

FontFamily.configure({
fontFamilyList: ['Arial', 'Georgia', { name: 'Monospace', value: 'monospace' }],
});
```

Use this configured extension in place of the unconfigured one in `extensions`.

---

# Font Size

Choose the font size used by selected text.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). Install `@tiptap/extension-text-style` at the same version as your other Tiptap packages. The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, FontSize, RichTextFontSize } from 'ai-sparkwrite-editor';
import { TextStyle } from '@tiptap/extension-text-style';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, TextStyle, FontSize];

export default function FontSizeExample() {
const editor = useEditor({
extensions,
content: 'Try this feature here.',
immediatelyRender: false,
});

if (!editor) return null;

return (

);
}
```

```vue [Vue]

```

:::

## How to use

Register `TextStyle`. Configure `fontSizes` with CSS sizes such as `14px` or objects such as `{ name: "Large", value: "24px" }`. Use `editor.chain().focus().setFontSize("18px").run()` or `unsetFontSize()` from your own controls.

## Compact variant

`` renders an icon button instead of a trigger
showing the current size. The wide trigger earns its space in a main toolbar,
where reading the size at a glance is the point; in a menu of named rows it is
the one control that will not line up, so the compact form matches the shape of
`RichTextLineHeight`.

## Configuration

```ts
import { FontSize } from 'ai-sparkwrite-editor';

FontSize.configure({
fontSizes: ['Default', '14px', '18px', { name: 'Large', value: '24px' }],
});
```

Use this configured extension in place of the unconfigured one in `extensions`.

---

# Format Painter

Copy inline formatting from one selection to another.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import {
RichTextProvider,
FormatPainter,
RichTextFormatPainter,
Bold,
RichTextBold,
} from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Bold, FormatPainter];

export default function FormatPainterExample() {
const editor = useEditor({
extensions,
content: 'Try this feature here.',
immediatelyRender: false,
});

if (!editor) return null;

return (

);
}
```

:::

::: warning React only
This feature's interactive UI depends on React libraries; the Vue layer does not include it yet. See [Frameworks](/guide/frameworks) for what the Vue entry covers.
:::

## How to use

Register the mark extensions you want to copy, such as Bold, Italic, Color, or FontSize. The painter copies existing marks; it does not add those features by itself. The example includes Bold so you can format a source selection before copying it.

## Behavior

1. Select text that already has the formatting you want to copy.
2. Click the format painter button.
3. Select the target text.
4. The copied marks are applied to the target selection and the format painter turns off automatically.

Press `Escape` or click the button again to cancel the format painter state.

## Commands

### setPainter

Copies the current selection marks and enables format painter mode.

```ts
editor.commands.setPainter();
```

### unsetPainter

Cancels format painter mode.

```ts
editor.commands.unsetPainter();
```

---

# Heading

Turn a paragraph into a heading with a chosen level.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, Heading, RichTextHeading } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Heading.configure({ levels: [1, 2, 3] })];

export default function HeadingExample() {
const editor = useEditor({
extensions,
content: 'Try this feature here.',
immediatelyRender: false,
});

if (!editor) return null;

return (

);
}
```

```vue [Vue]

```

:::

## How to use

Place the cursor in a paragraph and choose a level from the toolbar. `levels` controls the available heading levels; for example, `Heading.configure({ levels: [1, 2, 3] })`. Use `editor.chain().focus().toggleHeading({ level: 2 }).run()` for a custom action.

---

# Highlight

Apply a background highlight to selected text.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, Highlight, RichTextHighlight } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Highlight];

export default function HighlightExample() {
const editor = useEditor({
extensions,
content: 'Try this feature here.',
immediatelyRender: false,
});

if (!editor) return null;

return (

);
}
```

```vue [Vue]

```

:::

## How to use

Choose a color and select text to highlight. This extension enables multiple highlight colors by default. Set `Highlight.configure({ defaultColor: "#fef08a" })` to give the highlight shortcut an initial color. The commands are `setHighlight({ color: "#fef08a" })` and `unsetHighlight()`.

## Features

- 🎨 **Multiple Colors**: Support for multiple highlight colors
- ⌨️ **Keyboard Shortcuts**: Quick highlighting with `Mod-Shift-H`
- 🔄 **Smart Toggle**: Intelligent highlight toggling and replacement
- 🎯 **Synchronized Selection**: Color picker syncs between toolbar and bubble menu
- 🎨 **Custom Colors**: Add custom highlight colors via color picker
- 💾 **Recent Colors**: Automatically tracks recently used colors
- ❌ **No Fill Option**: Option to remove highlight

## Options

### defaultColor

Type: `string`\
Default: `undefined`

The default highlight color to use when the extension is initialized. This color will be used when applying highlight via keyboard shortcut for the first time.

```js
Highlight.configure({
defaultColor: '#ffff00', // Yellow
// or
defaultColor: '#ffc078', // Orange
});
```

### shortcutKeys

Type: `string[]`\
Default: `['⇧', 'mod', 'H']`

Shortcut label displayed by the control. The actual binding is `Mod-Shift-H` (Ctrl-Shift-H on Windows/Linux, Cmd-Shift-H on macOS). Changing this option does not rebind it; see [keyboard shortcuts](/guide/toolbar#keyboard-shortcuts).

```js
Highlight.configure({
shortcutKeys: ['⇧', 'mod', 'H'],
});
```

## Keyboard Shortcut Behavior

The `Mod-Shift-H` keyboard shortcut has intelligent toggle behavior:

1. **No highlight applied**: Applies the currently selected highlight color
2. **Same color already applied**: Removes the highlight (toggle off)
3. **Different color applied**: Replaces with the currently selected highlight color
4. **"No Fill" selected**: Does nothing (prevents applying undefined highlight)

## Color Selection Synchronization

The extension maintains a shared highlight color state across all instances:

- Selecting a color in the toolbar updates the bubble menu
- Selecting a color in the bubble menu updates the toolbar
- Keyboard shortcut uses the last selected color
- All color pickers show the same selected color
- Selecting "No Fill" clears the stored color

## Examples

### Basic Usage

```tsx
import { Highlight } from 'ai-sparkwrite-editor';

const extensions = [Highlight];
```

### With Default Color

```tsx
import { Highlight } from 'ai-sparkwrite-editor';

const extensions = [
Highlight.configure({
defaultColor: '#ffc078', // Orange highlight
}),
];
```

### Programmatic Usage

```tsx
// Apply highlight with color
editor.chain().focus().setHighlight({ color: '#ffff00' }).run();

// Remove highlight
editor.chain().focus().unsetHighlight().run();

// Toggle highlight (removes if same color, applies if different or none)
editor.chain().focus().toggleHighlight({ color: '#ffff00' }).run();

// Check if highlight is active
const isHighlightActive = editor.isActive('highlight');

// Check if specific color is active
const isYellowActive = editor.isActive('highlight', { color: '#ffff00' });

// Get current highlight color
const { color } = editor.getAttributes('highlight');
```

## Color Picker

The highlight color picker includes:

- **No Fill**: Remove highlight from text
- **Color Palette**: Predefined colors for quick selection
- **Recent Colors**: Last 10 used colors
- **Custom Color**: Pick any color using the color picker

## Differences from Color Extension

| Feature | Highlight | Color |
| ---------------- | ----------------------- | ------------------ |
| Purpose | Background highlighting | Text color |
| Default Shortcut | `Mod-Shift-H` | `Alt-Shift-C` |
| No Fill Behavior | Removes highlight | Removes text color |
| Visual Style | Background color | Foreground color |

---

# History

Undo and redo editing transactions.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, History, RichTextUndo, RichTextRedo } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, History];

export default function HistoryExample() {
const editor = useEditor({
extensions,
content: 'Try this feature here.',
immediatelyRender: false,
});

if (!editor) return null;

return (

);
}
```

```vue [Vue]

```

:::

## How to use

Register `History` once. It extends Tiptap 3’s `UndoRedo` extension, so do not also register `UndoRedo` or StarterKit’s undo history. The buttons become available when there is a change to undo or redo. Defaults are `depth: 100` and `newGroupDelay: 500` (milliseconds).

## Options

### shortcutKeys

Type: `string[][]`\
Default: `[['mod', 'Z'], ['shift', 'mod', 'Z']]`

Shortcut labels shown by the controls. See [keyboard shortcut configuration](/guide/toolbar#keyboard-shortcuts) to change actual key bindings.

---

# Horizontal Rule

Insert a horizontal separator between blocks.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, HorizontalRule, RichTextHorizontalRule } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, HorizontalRule];

export default function HorizontalRuleExample() {
const editor = useEditor({
extensions,
content: 'Try this feature here.',
immediatelyRender: false,
});

if (!editor) return null;

return (

);
}
```

:::

::: warning React only
This feature's interactive UI depends on React libraries; the Vue layer does not include it yet. See [Frameworks](/guide/frameworks) for what the Vue entry covers.
:::

## How to use

Place the cursor where the separator should appear, then click the toolbar button. The command is `editor.chain().focus().setHorizontalRule().run()`. Add Tiptap’s `TrailingNode` if you want a paragraph automatically created after a trailing non-paragraph block.

## Options

### shortcutKeys

Type: `string[]`\
Default: `['mod', 'alt', 'S']`

Shortcut labels shown by the controls. See [keyboard shortcut configuration](/guide/toolbar#keyboard-shortcuts) to change actual key bindings.

---

# Embed

The `Iframe` extension (`ai-sparkwrite-editor/iframe`), listed here under the name users see in the toolbar. Embed a YouTube video, a Figma file, a Google Sheet, a map, a CodePen — 35 services recognised from their share links — or any web page.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import {
RichTextProvider,
Iframe,
RichTextIframe,
RichTextBubbleIframe,
} from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Iframe];

export default function IframeExample() {
const editor = useEditor({
extensions,
content: 'Try this feature here.',
immediatelyRender: false,
});

if (!editor) return null;

return (

);
}
```

```vue [Vue]

```

:::

::: tip Vue
Not in the Vue layer yet: `RichTextBubbleIframe` — run the corresponding command from your own control, or see [Frameworks](/guide/frameworks).
:::

## How to use

Click **Embed** in the toolbar (or type `/embed`, `/youtube`, `/figma`…), then paste a **share link** — the kind you copy from the address bar — or the whole `` code from a service's _Embed_ dialog. The block recognises the service, converts the link to its embeddable URL, sizes the frame for it (16:9 for video, tall for forms) and shows which service it detected. Mount `RichTextBubbleIframe` for contextual controls (resize, open, delete).

| Services | Kind | What you get |
| ------------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| YouTube, Vimeo, Bilibili, Youku, Tencent Video, Loom, Descript | Video | 16:9 player |
| Spotify, SoundCloud | Audio | compact player |
| Google Maps, AMap, Baidu Maps | Maps | a place or search link becomes an embedded map; for short Google links use _Share → Embed a map_ and paste the code |
| Figma, Canva, Miro, Whimsical, Excalidraw, dbdiagram, ProcessOn, Modao, Lanhu, Framer | Design & whiteboards | live, pannable file |
| CodePen, CodeSandbox, StackBlitz, JSFiddle, GitHub Gist | Code | result or code view |
| Google Docs, Google Sheets, Google Slides, Airtable, Trello, ClickUp | Documents & data | read-only preview |
| Google Forms, Typeform, Jinshuju | Forms | the form itself |
| Any other `https://` page | Web page | shown as it is; the site decides whether it allows framing |

Some sites refuse to be framed (Notion pages, most banking or login pages); the frame then stays blank — that is the site's choice, not the editor's. Make sure your application's content-security policy allows the embedded origins.

## From code

```ts
import { resolveEmbed, EMBED_SERVICES } from 'ai-sparkwrite-editor';

const embed = resolveEmbed('https://youtu.be/I4sMhHbHYXM');
// { service: { key: 'youtube', name: 'YouTube', … }, src: 'https://www.youtube.com/embed/I4sMhHbHYXM', height: 338, url }

editor
.chain()
.focus()
.setIframe({ src: embed.src, service: embed.service.key, height: embed.height })
.run();
```

`EMBED_SERVICES` is the list of recognised services (key, name, kind, link pattern, example, tips); `resolveEmbed()` returns `null` for anything that is not a link. Saved HTML carries `data-service` on the `<iframe>` so a read-only page can style or label frames per service.

---



# Image

Insert images from a URL or an application-provided upload service.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, Image, RichTextImage, RichTextBubbleImage } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Image.configure({ resourceImage: 'link' })];

export default function ImageExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextImage />
<RichTextBubbleImage />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import {
Image,
RichTextProvider,
RichTextImage,
RichTextBubbleImage,
} from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Image.configure({ resourceImage: 'link' })];

const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<RichTextImage />
<RichTextBubbleImage />
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

## How to use

The example starts in URL-only mode so it works without a backend. To enable local files, configure `resourceImage: "both"` or `"upload"` and provide `upload: (file: File) => Promise<string>`. Return a durable image URL; temporary `blob:` URLs will not survive a reload. Mount `RichTextBubbleImage` for image editing controls.

## Inline and block images

`Image.configure()` now registers both image node types used by the editor:

- `image`: the legacy inline node, kept for existing ProseMirror JSON compatibility.
- `imageBlock`: a block-level node used when `defaultInline` is `false` or when `setImageInline({ inline: false })` / `setImageBlock()` inserts an image.

Existing HTML is still accepted:

- `<div class="image"><img ... /></div>` is parsed as `imageBlock`.
- `<p><div class="image"><img inline="false" ... /></div></p>` produced by versions before 1.0.26 is parsed as `imageBlock` without the empty paragraphs the browser adds around it, so the document no longer grows on each save/load.
- `<span class="image"><img inline="true" ... /></span>` is parsed as the inline `image` node.
- Old JSON with `type: "image"` continues to load. If you want to migrate stored JSON, use `migrateImageJSONToImageBlock(json)` before saving the migrated document.

## Image Gif

To search a GIF provider and insert a result, use the separate [ImageGif extension](/extensions/ImageGif/index.md).

## Props

```ts
interface IImageOptions extends GeneralOptions<IImageOptions> {
/** Function for uploading files */
upload?: (file: File) => Promise<string>;

HTMLAttributes?: any;

multiple?: boolean;
acceptMimes?: string[];
maxSize?: number;

/** The source URL of the image */
resourceImage: 'upload' | 'link' | 'both';
defaultInline?: boolean;

enableAlt?: boolean;

onError?: (error: { type: 'size' | 'type' | 'upload'; message: string; file?: File }) => void;
}
```

| Property | Type | Description | Required | Default |
| ---------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | -------------------------------------------------------------------------- |
| `upload` | `(file: File) => Promise<string>` | Custom image upload function that receives a `File` and returns a Promise with the image URL, suitable for uploading to cloud or local servers. | No | None |
| `HTMLAttributes` | `any` | HTML attributes passed to the `<img>` tag, such as `className`, `style`, `alt`, etc. | No | None |
| `multiple` | `boolean` | Whether to allow selecting and uploading multiple images simultaneously. | No | `true` |
| `acceptMimes` | `string[]` | List of allowed image MIME types or file extension restrictions, such as `['image/jpeg', 'image/png']`, `['image/*']`, or `['.png', '.jpg']`, etc. Supports MIME type wildcards and precise file extension restrictions. | No | Common image types `['image/jpeg', 'image/gif', 'image/png', 'image/jpg']` |
| `maxSize` | `number` | Maximum size limit for a single image (in bytes), triggers `onError` when exceeded. | No | `5MB` |
| `resourceImage` | `'upload' \| 'link' \| 'both'` | Image source method: - `'upload'`: Upload only - `'link'`: Link only - `'both'`: Both supported | No | `both` |
| `defaultInline` | `boolean` | Whether to insert images as inline elements by default. | No | `false` |
| `enableAlt` | `boolean` | Whether to enable alt text editing for images. | No | `true` |
| `onError` | `(error: { type: 'size' \| 'type' \| 'upload'; message: string; file?: File }) => void` | Callback function for upload or validation failures. Contains error type (size, type, upload), error message, and corresponding file. | No | None |

### resourceImage Type Description

- `'upload'`: Users can only select local files for upload
- `'link'`: Users can only input image URLs
- `'both'`: Supports both upload and URL methods

### acceptMimes Usage Instructions

Supports three format types:

1. **MIME types**: such as `['image/jpeg', 'image/png']`
2. **Wildcard types**: such as `['image/*']`, matches all image MIME types
3. **Extension types**: such as:

```ts
[
'.png',
'.jpg',
'.jpeg',
'.webp',
'.gif',
'.svg',
'.svgz',
'.xbm',
'.tiff',
'.ico',
'.jfif',
'.heic',
'.heif',
'.avif',
'.bmp',
'.apng',
'.pjpeg',
];
```

### onError Example

- Customize error handling logic to unify system prompts.
- We recommend using the message field, which has built-in dynamic prompts and i18n internationalization support.

```ts
onError: ({ type, message, file }) => {
switch (type) {
case 'size':
console.warn(`File size exceeds limit: ${file?.name}`);
break;
case 'type':
console.warn(`Unsupported file type: ${file?.type}`);
break;
case 'upload':
console.error(`Upload failed: ${message}`);
break;
}
};
```

## Upload a local image

Replace the URL-only configuration in the setup example with this one. Implement `/api/images` in your application so it accepts a multipart `file` and returns a JSON object with a `url` string:

```ts
Image.configure({
resourceImage: 'both',
upload: async (file: File): Promise<string> => {
const body = new FormData();
body.append('file', file);
const response = await fetch('/api/images', { method: 'POST', body });
if (!response.ok) throw new Error('Image upload failed');
const data = await response.json();
if (typeof data.url !== 'string' || !data.url) {
throw new Error('Upload response must contain an image URL');
}
return data.url;
},
});
```

The library handles the editor UI; your application supplies storage and the upload endpoint. Enforce accepted file types and size limits on that endpoint as well as in the client configuration.

## Options

Everything about the insert dialog is configured on the extension:

```tsx
Image.configure({
// Required to store files anywhere other than a blob: URL.
upload: async (file) => (await uploadToYourApi(file)).url,

// Accepted types, as an `accept` list. The dialog shows the first few of
// these plus the size limit under the drop zone.
acceptMimes: ['image/jpeg', 'image/png', 'image/gif', 'image/webp'],

// Per-file limit in bytes. Default: 5 MB.
maxSize: 10 * 1024 * 1024,

// Whether more than one file can be picked or dropped at a time. Default: true.
multiple: true,

// 'upload' | 'link' | 'both'. Controls which tabs the dialog shows.
resourceImage: 'both',

// Insert images inline with text rather than as their own block. Default: false.
defaultInline: false,

// Ask for alt text while inserting. Default: false — most editors let you
// set it afterwards rather than interrupting the insert.
enableAlt: false,

// Called instead of the built-in toast when a file is rejected or fails.
onError: ({ type, message, file }) => reportToYourApp(type, message, file),
});
```

The default `acceptMimes` covers JPEG, PNG, GIF, WebP, AVIF, BMP, TIFF, HEIC,
HEIF and SVG. Note on SVG: it is inert inside an `<img>`, but it can carry
script, so a host that serves uploads as top-level documents from its own origin
should sanitise them or serve them from a separate origin. Drop `'image/svg+xml'`
from `acceptMimes` if you would rather not accept it at all.

## Captions and rotation

Mount `RichTextBubbleImage` to get the image controls. Two of them are worth
calling out:

- **Rotate** turns the image a quarter turn per click, storing the angle in the
node's `rotate` attribute and serialising it as `data-rotate` on the `<img>`.
The older `flipx` / `flipy` attributes are still parsed, so documents written
by earlier versions keep their flips.
- **Caption** adds a single caption under a block image, stored in the `caption`
attribute and serialised as `<div class="image-caption">` inside the image
wrapper. It follows the image's alignment. Clearing the text removes the
caption, and the button then adds a fresh one. Inline images have no caption,
so the button is disabled for them.

## Uploads and deleted images

`upload` runs as soon as a file is chosen, so a picture reaches your server
before the document is saved. If the user then deletes the picture, or never
saves, the server keeps a file nothing refers to. The extension tracks enough
to clean that up at save time:

```ts
import { getImageChanges, markImagesSaved } from 'ai-sparkwrite-editor';

async function save(editor: Editor) {
const { current, removed, orphaned } = getImageChanges(editor);

await api.saveDocument({ html: editor.getHTML(), images: current });
// `removed`: in the last saved version, gone now.
// `orphaned`: uploaded in this session, not in the document — inserted and
// deleted again, or cropped and replaced.
await api.deleteImages([...removed, ...orphaned]);

markImagesSaved(editor);
}
```

- `getImageChanges(editor, previous?)` compares the document with a snapshot of
image sources: the one `markImagesSaved` recorded, or one you pass in (for
example the list stored with the document on the server, so the first save
after a reload still finds deletions). It returns `current`, `added`,
`removed` and `orphaned`.
- `markImagesSaved(editor)` records the current sources as the new baseline and
stops counting them as orphans.
- `collectImageSources(doc)` lists the sources in any document, for the server
side of the comparison.

Undo can bring a deleted picture back, so delete server files at save time and
not on every edit. Only sources returned by `upload` are ever reported as
orphaned; pasted or linked URLs are not.

---



# ImageGif

Search for animated GIFs and insert one into the document.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import {
RichTextProvider,
ImageGif,
RichTextImageGif,
RichTextBubbleImageGif,
} from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [
Document,
Paragraph,
Text,
ImageGif.configure({ provider: 'giphy', API_KEY: 'YOUR_GIPHY_API_KEY' }),
];

export default function ImageGifExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextImageGif />
<RichTextBubbleImageGif />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { ImageGif, RichTextProvider } from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

const extensions = [
Document,
Paragraph,
Text,
ImageGif.configure({ provider: 'giphy', API_KEY: 'YOUR_GIPHY_API_KEY' }),
];

const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

::: tip Vue
Not in the Vue layer yet: `RichTextImageGif`, `RichTextBubbleImageGif` — run the corresponding command from your own control, or see [Frameworks](/guide/frameworks).
:::

## How to use

Set `provider` to `"giphy"` (the default) or `"tenor"`, and supply that provider’s `API_KEY`. The placeholder in the example must be replaced for search to work. Click the GIF button, search, and choose a result. Mount `RichTextBubbleImageGif` for contextual editing.

---



# Import Word

Convert a Word `.docx` file into editor content.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, ImportWord, RichTextImportWord } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, ImportWord];

export default function ImportWordExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextImportWord />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { ImportWord, RichTextProvider } from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, ImportWord];

const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

::: tip Vue
Not in the Vue layer yet: `RichTextImportWord` — run the corresponding command from your own control, or see [Frameworks](/guide/frameworks).
:::

## How to use

Click the toolbar button and choose a `.docx` file. Import replaces the current document, so save existing work first. The default file-size limit is 10 MiB. Converted HTML is parsed by the active schema, so register the formatting, list, table, and image extensions you want to preserve. Word page layout is not guaranteed to survive conversion.

## Configuration

| Option | Purpose | Default |
| ---------------- | ------------------------------------------------------------------ | ---------------------------- |
| `limit` | Maximum `.docx` file size in bytes. | `10 * 1024 * 1024`. |
| `convert` | Custom `(file: File) => Promise<string>` converter returning HTML. | Built-in Mammoth conversion. |
| `mammothOptions` | Options passed to the built-in HTML converter. | Omitted. |
| `upload` | Upload embedded images extracted from the converted HTML. | Omitted. |

For example, replace `ImportWord` in your array with:

```ts
import { ImportWord } from 'ai-sparkwrite-editor';

ImportWord.configure({
limit: 5 * 1024 * 1024,
});
```

### Embedded images

Register the library's `Image` extension to preserve imported images. The ImportWord `upload` handler receives a `File[]` and must resolve to an array of `{ src: string }` objects in the same order. This differs from the Image extension's upload handler, which receives one file and returns one URL string.

Without this handler, converted image sources remain in the HTML. The current upload processing expects base64 image sources from conversion; a custom `convert` implementation returning remote image URLs should handle image storage itself and omit this upload handler.

## Loading behavior

The built-in Mammoth converter loads after a valid file is selected. A custom `convert` callback bypasses the built-in converter. The first import may take longer while the conversion code loads.

---



# Indent

Increase or decrease indentation of supported blocks.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, Indent, RichTextIndent } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Indent];

export default function IndentExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextIndent />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { Indent, RichTextProvider, RichTextIndent } from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Indent];

const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<RichTextIndent />
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

## How to use

Place the cursor in a paragraph and use the indent controls. For list nesting, register the corresponding list and item extensions too. Indentation changes layout; it does not insert spaces into the text.

## Options

### shortcutKeys

Type: `string[][]`\
Default: `[['Tab'], ['Shift', 'Tab']]`

Shortcut labels shown by the controls. See [keyboard shortcut configuration](/guide/toolbar#keyboard-shortcuts) to change actual key bindings.

---



# Italic

Apply italic emphasis to selected text.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, Italic, RichTextItalic } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Italic];

export default function ItalicExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextItalic />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { Italic, RichTextProvider, RichTextItalic } from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Italic];

const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<RichTextItalic />
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

## How to use

Select text and click **Italic**, or enable it before typing. The command is `editor.chain().focus().toggleItalic().run()`.

## Options

### shortcutKeys

Type: `string[]`\
Default: `['mod', 'I']`

Shortcut labels shown by the controls. See [keyboard shortcut configuration](/guide/toolbar#keyboard-shortcuts) to change actual key bindings.

---



# Katex

Insert mathematical expressions written in TeX syntax.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, Katex, RichTextKatex, RichTextBubbleKatex } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';
import 'katex/dist/katex.min.css';

const extensions = [Document, Paragraph, Text, Katex];

export default function KatexExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextKatex />
<RichTextBubbleKatex />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { Katex, RichTextProvider, RichTextKatex } from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';
import 'katex/dist/katex.min.css';

const extensions = [Document, Paragraph, Text, Katex];

const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<RichTextKatex />
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

::: tip Vue
Not in the Vue layer yet: `RichTextBubbleKatex` — run the corresponding command from your own control, or see [Frameworks](/guide/frameworks).
:::

## How to use

Load `katex/dist/katex.min.css` alongside the editor stylesheet. Open the toolbar dialog, enter an expression such as `E = mc^2`, and apply it. Mount `RichTextBubbleKatex` for contextual actions. Install `katex` directly in your app if your package manager cannot resolve the CSS import.

## Renderer loading and chemistry

The renderer loads when a formula node view mounts or a formula dialog opens. Until it is ready, the preview displays the expression as text. Existing formulas can therefore trigger loading on the first editor render. A failed load offers a retry button; invalid formulas remain text. Rendering happens on the client, so server output does not contain rendered formula HTML.

Use the optional `loadKatex` configuration to initialize plugins before rendering. For chemistry commands such as `\ce{H2O}`, install `katex` directly and replace `Katex` in the extension array with:

```ts
import { Katex } from 'ai-sparkwrite-editor';
import 'katex/dist/katex.min.css';

Katex.configure({
loadKatex: async () => {
const [{ default: katex }] = await Promise.all([
import('katex'),
import('katex/contrib/mhchem'),
]);
return katex;
},
});
```

If TypeScript cannot find types for mhchem, add this declaration to an ambient `.d.ts` file:

```ts
declare module 'katex/contrib/mhchem';
```

The loader must resolve to the KaTeX renderer, not the module namespace. Its promise is shared across node views and dialogs using the same loader function; failed loads can be retried. Keep the loader function stable. CSS remains an explicit static import. Avoid a static JavaScript import of KaTeX or mhchem elsewhere if you want the renderer to stay in an asynchronous chunk.

---



# Line Height

Apply a line-height value through the text-style mark.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). Install `@tiptap/extension-text-style` at the same version as your other Tiptap packages. The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, LineHeight, RichTextLineHeight } from 'ai-sparkwrite-editor';
import { TextStyle } from '@tiptap/extension-text-style';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, TextStyle, LineHeight];

export default function LineHeightExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextLineHeight />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { TextStyle } from '@tiptap/extension-text-style';
import { LineHeight, RichTextProvider, RichTextLineHeight } from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, TextStyle, LineHeight];

const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<RichTextLineHeight />
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

## How to use

Register `TextStyle`. Select text, then choose a value from the dropdown. `Default` removes the explicit line height. Configure the choices with `lineHeights`; the values are CSS line heights, such as `1.5` or `2`.

## Configuration

```ts
import { LineHeight } from 'ai-sparkwrite-editor';

LineHeight.configure({
lineHeights: ['Default', '1.5', '2', '2.5'],
});
```

Use this configured extension in place of the unconfigured one in `extensions`. The default choices are `Default`, `1.5`, `2`, `2.5`, `3`, `3.5`, and `4`.

---



# Link

Add or edit a hyperlink on text.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, Link, RichTextLink, RichTextBubbleLink } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Link];

export default function LinkExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextLink />
<RichTextBubbleLink />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { Link, RichTextProvider, RichTextLink, RichTextBubbleLink } from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Link];

const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<RichTextLink />
<RichTextBubbleLink />
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

## How to use

Select the text to link, open the toolbar dialog, and enter a URL. Mount `RichTextBubbleLink` to edit a link after selecting it. Use `editor.chain().focus().setLink({ href: "https://example.com" }).run()` to apply a link to a selection, and `unsetLink()` to remove it.

---



# Mention

Insert structured mentions using a trigger such as `@`.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, Mention } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const users = [
{ id: '1', label: 'Alex' },
{ id: '2', label: 'Sam' },
];

const extensions = [
Document,
Paragraph,
Text,
Mention.configure({
suggestion: {
char: '@',
items: ({ query }) =>
users.filter((user) => user.label.toLowerCase().startsWith(query.toLowerCase())),
},
}),
];

export default function MentionExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

:::

::: warning React only
This feature's interactive UI depends on React libraries; the Vue layer does not include it yet. See [Frameworks](/guide/frameworks) for what the Vue entry covers.
:::

## How to use

Type `@` followed by a name to filter suggestions. Return objects with stable `id` and display `label` fields from `items`; an `avatar` is optional. The library supplies a suggestion renderer when you configure `suggestion` or `suggestions`. There is no separate mention toolbar button. For remote search, replace the filter with an async request returning the same shape.

## Multiple triggers

Use `suggestions` to provide separate sources for people and tags. Replace the single `suggestion` configuration with this setup:

```ts
import { Mention } from 'ai-sparkwrite-editor';

const people = [{ id: 'user-1', label: 'Alex' }];
const tags = [{ id: 'tag-1', label: 'Documentation' }];

Mention.configure({
suggestions: [
{
char: '@',
items: ({ query }) =>
people.filter((item) => item.label.toLowerCase().startsWith(query.toLowerCase())),
},
{
char: '#',
items: ({ query }) =>
tags.filter((item) => item.label.toLowerCase().startsWith(query.toLowerCase())),
},
],
});
```

Use the arrow keys to move through suggestions and Enter to insert one. The mention stores the selected identifier and label; it does not send a notification or update a user record automatically.

---



# Mermaid

Create editable diagrams from Mermaid source text.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import {
RichTextProvider,
Mermaid,
RichTextMermaid,
RichTextBubbleMermaid,
} from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Mermaid];

export default function MermaidExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextMermaid />
<RichTextBubbleMermaid />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { Mermaid, RichTextProvider, RichTextMermaid } from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Mermaid];

const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<RichTextMermaid />
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

::: tip Vue
Not in the Vue layer yet: `RichTextBubbleMermaid` — run the corresponding command from your own control, or see [Frameworks](/guide/frameworks).
:::

## How to use

Click the toolbar button, enter diagram source, and apply it to insert a diagram. Mount `RichTextBubbleMermaid` for contextual actions. Keep the Mermaid extension registered when reopening saved diagram nodes.

---



# More Mark

Add subscript and superscript formatting for formulas, references, and annotations.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, MoreMark, RichTextMoreMark } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, MoreMark];

export default function MoreMarkExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextMoreMark />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { MoreMark, RichTextProvider } from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, MoreMark];

const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

::: tip Vue
Not in the Vue layer yet: `RichTextMoreMark` — run the corresponding command from your own control, or see [Frameworks](/guide/frameworks).
:::

## How to use

The extension registers subscript and superscript marks for you. Select text and choose the desired mark from the menu. Disable one with `MoreMark.configure({ subscript: false })` or `{ superscript: false }`; avoid registering duplicate standalone marks.

## Options

### shortcutKeys

Type: `string[][]`\
Default: `[['mod', '.'], ['mod', ',']]`

Shortcut labels shown by the controls. See [keyboard shortcut configuration](/guide/toolbar#keyboard-shortcuts) to change actual key bindings.

---



# Notice

A coloured box with an icon — **Info**, **Success**, **Warning** or **Tip** — holding ordinary editable blocks: paragraphs, lists, code, tables. The kind of block most document editors offer under "+ → Info notice".

<div class="notice" data-type="success"><p><strong>Saved as plain HTML.</strong> A notice is <code><div class="notice" data-type="success"></code> around normal blocks, so the saved document renders the same box anywhere the stylesheet is loaded — no node view, no custom renderer.</p></div>

## Setup

Start with the packages in [Getting Started](/guide/getting-started). `RichTextKit` already includes the notice (option `notice`). To assemble it yourself:

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import {
RichTextProvider,
Notice,
RichTextNotice,
RichTextBubbleNotice,
} from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Notice];

export default function NoticeExample() {
const editor = useEditor({
extensions,
content: '<div class="notice" data-type="info"><p>Try this feature here.</p></div>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextNotice />
<RichTextBubbleNotice />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import {
Notice,
RichTextProvider,
RichTextNotice,
RichTextBubbleNotice,
} from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Notice];

const editor = useEditor({
extensions,
content: '<div class="notice" data-type="info"><p>Try this feature here.</p></div>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<RichTextNotice />
<RichTextBubbleNotice />
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

## How to use

- **Toolbar**: `RichTextNotice` is a dropdown of the four types. Picking one wraps the selected blocks (or the current paragraph); picking the type of the notice you are in removes it; picking another type changes it.
- **Slash menu**: one "Notice" row with the four types as coloured icons at its right — ←/→ or a click picks the type, Enter inserts. Typing `/warning` (or `/success`, `/tip`, `/info`) preselects that type.
- **Bubble menu**: `RichTextBubbleNotice` appears above the notice the caret is in, with the four types and a remove button.
- **Keyboard**: Enter on an empty last line leaves the box, the way lists end. Backspace at the start of the first line pulls that line out (an empty box disappears); Backspace on the line right after a box joins it to the box's last paragraph, and Delete at the end of the box pulls the next line in — two boxes never fuse into one.

## Saved format

```html
<div class="notice" data-type="warning">
<p>Publishing replaces the live page.</p>
<ul>
<li><p>Check the table first.</p></li>
</ul>
</div>
```

`data-type` is one of `info`, `success`, `warning`, `tip`; anything else is read back as `info`. The colours and icons come from the stylesheet (`.notice[data-type='…']`), so a read-only page needs only `ai-sparkwrite-editor/style.css`. Override `--notice-color`, `--notice-background` and `--notice-icon` per type to restyle.

Markdown export writes GitHub-style alerts: `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, and `> [!SUCCESS]` (which other renderers show as a plain quote).

## Commands

```ts
editor.chain().focus().setNotice('tip').run(); // wrap the selection
editor.chain().focus().toggleNotice('warning').run(); // wrap, retype, or remove
editor.chain().focus().updateNotice('success').run(); // change the type
editor.chain().focus().unsetNotice().run(); // lift the blocks out
```

`NOTICE_TYPES` lists the types and their colours; `getNoticeType()` normalises unknown values.

---



# Ordered List

Organize paragraphs into a numbered list.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). Install `@tiptap/extension-list` at the same version as your other Tiptap packages. The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, OrderedList, RichTextOrderedList } from 'ai-sparkwrite-editor';
import { ListItem } from '@tiptap/extension-list';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, ListItem, OrderedList];

export default function OrderedListExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextOrderedList />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { ListItem } from '@tiptap/extension-list';
import { OrderedList, RichTextProvider, RichTextOrderedList } from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, ListItem, OrderedList];

const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<RichTextOrderedList />
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

## How to use

Register `ListItem` alongside `OrderedList`. Select paragraphs and click the numbered-list button, or call `editor.chain().focus().toggleOrderedList().run()`.

## Options

### shortcutKeys

Type: `string[]`\
Default: `['mod', 'shift', '7']`

Shortcut labels shown by the controls. See [keyboard shortcut configuration](/guide/toolbar#keyboard-shortcuts) to change actual key bindings.

---



# Recorder

Records every edit as timestamped ProseMirror steps, so a writing session can be saved and played back like a screen recording of the document. Use it for audit trails, "show me how this was written", collaborative review, or reproducing a bug report exactly.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The extension has no toolbar control; you decide when to record and when to replay.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, Recorder, getRecording, replayRecording } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Recorder.configure({ autoStart: true })];

export default function RecorderExample() {
const editor = useEditor({ extensions, content: '<p>Type here.</p>', immediatelyRender: false });

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<button onClick={() => editor.commands.stopRecording()}>Stop</button>
<button
onClick={() => {
const recording = getRecording(editor);
if (recording) void replayRecording(editor, recording, { speed: 4 });
}}
>
Replay ×4
</button>
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import {
Recorder,
getRecording,
replayRecording,
RichTextProvider,
} from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Recorder.configure({ autoStart: true })];

const editor = useEditor({
extensions,
content: '<p>Type here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<button onClick={() => editor.commands.stopRecording()}>Stop</button>
<button
onClick={() => {
const recording = getRecording(editor);
if (recording) void replayRecording(editor, recording, { speed: 4 });
}}
>
Replay ×4
</button>
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

## How it works

`startRecording()` snapshots the document as JSON. From then on every transaction that changes the document (or, with `recordSelection`, moves the caret) is appended as `{ t, steps, selection }`, where `t` is milliseconds since the start and `steps` are the ProseMirror steps as JSON. `stopRecording()` closes it. The result lives in `editor.storage.recorder.recording` and `getRecording(editor)` returns it — plain JSON you can `JSON.stringify` and store.

`replayRecording(editor, recording, options)` resets the editor to the snapshot and applies the entries with the original pauses, scaled by `speed` and capped by `maxDelay`. Replayed transactions are neither recorded again nor added to the undo history. Make the editor read-only during playback if the viewer should only watch; pass an `AbortSignal` to stop early.

A recording is tied to the schema it was made with. Replaying it in an editor with different extensions can fail, in which case the promise rejects with the failing entry index.

## Saving as you go

`onEntry` fires for each entry, so you can stream a session to a server or persist incrementally:

```ts
Recorder.configure({
autoStart: true,
onEntry: (entry, recording) => {
// POST entry, or debounce and save `recording` whole.
},
});
```

## Commands

- `editor.commands.startRecording()` — starts a new recording from the current document.
- `editor.commands.stopRecording()` — stops it; returns `false` when nothing was recording.

## Options

### autoStart

Type: `boolean`\
Default: `false`

Start recording when the editor is created.

### recordSelection

Type: `boolean`\
Default: `true`

Also record caret and selection changes, so a replay shows where the author was looking. Turn it off for smaller recordings.

### onEntry

Type: `(entry: RecordingEntry, recording: Recording) => void`\
Default: none

Called for every recorded entry.

### maxEntries

Type: `number`\
Default: `0` (unlimited)

When the recording grows past this many entries it restarts from the current document, so memory stays bounded for very long sessions. Pair it with `onEntry` if you need the full history.

## Replay options

`replayRecording(editor, recording, { speed, maxDelay, onProgress, signal })`

- `speed` — `1` is real time, `4` is four times faster.
- `maxDelay` — the longest pause kept, in real-time milliseconds (default `2000`).
- `onProgress(index, total)` — after each entry.
- `signal` — an `AbortSignal` to stop.

---



# Rich Paste

Fixes the two pastes browsers get wrong: Word lists and code copied from a code editor.

Pasting from a web page, Excel, Google Docs or Word already keeps headings, bold, links, tables and colours, because the HTML on the clipboard maps onto the editor schema. Two sources do not:

- **Word lists.** Word does not put `<ul>` or `<ol>` on the clipboard. Each item is a paragraph with an `mso-list` style and a literal bullet character in front, so a list arrives as plain paragraphs starting with `·`. This extension rebuilds the run as a real nested list, reading the nesting depth from Word's `level` and choosing a numbered list when the marker is `1.`, `a)` or `iv.`.
- **Code editors.** VS Code, Sublime, Xcode and JetBrains copy one coloured `<span>` per token inside a monospace, `white-space: pre` container. That would land as paragraphs of coloured text. This extension recognises the container and inserts a code block from the plain-text copy instead. A single line becomes inline code rather than a block.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). This complete example registers the feature. It has no toolbar control; add it next to `CodeBlock`, `BulletList` and `OrderedList` so there is something to paste into.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import {
RichTextProvider,
BulletList,
CodeBlock,
OrderedList,
RichPaste,
} from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, BulletList, OrderedList, CodeBlock, RichPaste];

export default function RichPasteExample() {
const editor = useEditor({
extensions,
content: '<p>Paste a Word list or a snippet from VS Code here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import {
BulletList,
OrderedList,
RichPaste,
CodeBlock,
RichTextProvider,
} from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, BulletList, OrderedList, CodeBlock, RichPaste];

const editor = useEditor({
extensions,
content: '<p>Paste a Word list or a snippet from VS Code here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

## Options

### wordLists

Type: `boolean`\
Default: `true`

Rebuild Word's list paragraphs as lists.

### codeBlocks

Type: `boolean`\
Default: `true`

Paste from a code editor as a code block.

### detectLanguage

Type: `(code: string) => string`\
Default: none

Guesses the language of a pasted block from its text and returns a name the code block understands (an empty string means "unknown"). The code block extension ships a guesser you can reuse:

```ts
import { guessLanguage } from 'ai-sparkwrite-editor';

RichPaste.configure({ detectLanguage: guessLanguage });
```

## What is not changed

Pasting inside a code block is left to the default behaviour, which already keeps the text. HTML that contains paragraphs, headings, tables or lists is never treated as code, even when it uses a monospace font.

---



# Search And Replace

Find text in the document and replace individual matches or all matches.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, SearchAndReplace, RichTextSearchAndReplace } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, SearchAndReplace];

export default function SearchAndReplaceExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextSearchAndReplace />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { SearchAndReplace, RichTextProvider } from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, SearchAndReplace];

const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

::: tip Vue
Not in the Vue layer yet: `RichTextSearchAndReplace` — run the corresponding command from your own control, or see [Frameworks](/guide/frameworks).
:::

## How to use

Open the toolbar dialog, enter a search term, and use the match navigation before replacing. Register [History](/extensions/History/) if users should be able to undo replacements.

## Props

| Prop | Type | Description | Default |
| -------------------------- | ------------ | --------------------------- | ------------------------- |
| `searchTerm` | `string` | Search Term | `''` |
| `replaceTerm` | `string` | Replace Term | `''` |
| `searchResultClass` | `string` | Search Result Class | `'search-result'` |
| `searchResultCurrentClass` | `string` | Search Result Current Class | `'search-result-current'` |
| `caseSensitive` | `boolean` | Case Sensitive | `false` |
| `disableRegex` | `boolean` | Disable Regex | `false` |
| `onChange` | `() => void` | On Change | `undefined` |

---



# Short Message

Insert predefined snippets from a list that opens with a keyboard shortcut (`Ctrl+Space` / `Cmd+Space` by default).

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, ShortMessage } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [
Document,
Paragraph,
Text,
ShortMessage.configure({
messages: [
{ short: 'nsfw', long_content: 'Not safe forward' },
{ short: 'brb', long_content: 'Be right back' },
{ short: 'sig', long_content: '<p>Best regards,<br><strong>Alex</strong></p>' },
],
}),
];

export default function ShortMessageExample() {
const editor = useEditor({
extensions,
content: '<p>Press Ctrl+Space here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

:::

::: warning React only
This feature's interactive UI depends on React libraries; the Vue layer does not include it yet. See [Frameworks](/guide/frameworks) for what the Vue entry covers.
:::

## How to use

Place the caret inside a paragraph and press the shortcut. A list of every configured message appears at the caret. Keep typing to filter it; the filter matches the start of `short` first, then anything containing the text in `short` or `long_content`. Use the arrow keys to move through the list and Enter (or a click) to insert. The text typed while the list was open is replaced by `long_content`. Escape closes the list and keeps what you typed. Moving the caret out of the current block or clicking outside the editor also closes it. There is no toolbar button.

`long_content` is inserted with `insertContent`, so it may contain simple HTML such as `<strong>` or `<br>`. Plain strings are inserted as text.

## Options

| Option | Type | Default | Description |
| ---------- | -------------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------- |
| `messages` | `{ short: string; long_content: string }[]` | `[]` | Messages shown in the list. `short` is displayed and used for filtering. |
| `shortcut` | `string` | `'Mod-Space'` | Tiptap keyboard shortcut that opens the list. |
| `items` | `({ query, editor }) => ShortMessageItem[] \| Promise<ShortMessageItem[]>` | — | Replaces the built-in filter. Receives the text typed after the shortcut; may be async. |

### Custom shortcut

`shortcut` uses the Tiptap/ProseMirror keymap syntax: modifiers and the key are joined with `-` (not `+`), e.g. `Mod-Space`, `Shift-Space`, `Ctrl-Alt-m`. Available modifiers are `Mod` (Ctrl on Windows/Linux, Cmd on macOS), `Ctrl`, `Alt`, `Shift`, and `Cmd`/`Meta`. Key names are case-sensitive and follow `KeyboardEvent.key` (`Space`, `Enter`, `ArrowUp`, `F2`, `a`, `/`). A value such as `shift+space` is treated as a single unknown key name and never fires. See the [Tiptap keyboard shortcuts guide](https://tiptap.dev/docs/editor/core-concepts/keyboard-shortcuts) for the full list.

`Ctrl+Space` is reserved by some input methods (for example IME toggles on Windows or input-source switching on macOS). Pick another combination when that is a concern:

```ts
ShortMessage.configure({
shortcut: 'Mod-Shift-Space',
messages: [{ short: 'ty', long_content: 'Thank you!' }],
});
```

### Remote messages

Use `items` to fetch messages from an API instead of a static list:

```ts
ShortMessage.configure({
items: async ({ query }) => {
const res = await fetch(`/api/snippets?q=${encodeURIComponent(query)}`);
return res.json(); // [{ short, long_content }]
},
});
```

---



# Slash Command

Open an insertion menu by typing `/` in the document.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, SlashCommand, SlashCommandList, Heading } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Heading, SlashCommand];

export default function SlashCommandExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<SlashCommandList />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

:::

::: warning React only
This feature's interactive UI depends on React libraries; the Vue layer does not include it yet. See [Frameworks](/guide/frameworks) for what the Vue entry covers.
:::

## How to use

Register `SlashCommand` and mount `SlashCommandList` inside the provider. The component supplies the command list; the extension handles the trigger and popup. Type `/` in an empty paragraph, filter the list, and choose an item. Register the extensions used by the commands you offer.

## Supply your own command list

Use `commandList` on `SlashCommandList` to replace the default groups. Each group has a `name`, `title`, and `commands` array. A command receives the editor and the range containing the slash query.

```tsx
import { SlashCommandList } from 'ai-sparkwrite-editor';

export function CustomSlashCommands() {
return (
<SlashCommandList
commandList={[
{
name: 'insert',
title: 'Insert',
commands: [
{
name: 'greeting',
label: 'Greeting',
description: 'Insert a short greeting',
aliases: ['hello'],
action: ({ editor, range }) => {
editor.chain().focus().deleteRange(range).insertContent('<p>Hello!</p>').run();
},
},
],
},
]}
/>
);
}
```

Mount `CustomSlashCommands` in place of the default `SlashCommandList`. Removing `range` prevents the typed slash query from remaining in the document. If an action calls a feature-specific command, register that feature too. Use `shouldBeHidden: (editor) => boolean` to omit a command when its prerequisites are unavailable.

Set `hiddenUntilSearched: true` to keep a command out of the menu until the reader types something matching its label or aliases. It is for entries that are worth having but not worth the space at rest — the default list uses it for headings 4 to 6, so that Table and Code block are not pushed below the fold.

## Default list

The default groups are _Format_ (paragraph, headings 1 to 3, bullet, numbered and task lists, quote) and _Insert_ (table, code block, image, divider, columns, toggle list, video, table of contents), plus an _AI_ entry at the top when the AI extension is registered. Headings 4 to 6 appear once searched.

An omitted or empty `commandList` uses the default list. The command-list store is currently shared across editor instances, so mounting different lists in multiple editors can overwrite one another.

---



# Strike

Mark text with a strikethrough while keeping the text in the document.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, Strike, RichTextStrike } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Strike];

export default function StrikeExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextStrike />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { Strike, RichTextProvider, RichTextStrike } from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Strike];

const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<RichTextStrike />
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

## How to use

Select text and click the strikethrough button. Use `editor.chain().focus().toggleStrike().run()` from a custom control.

## Options

### shortcutKeys

Type: `string[]`\
Default: `['shift', 'mod', 'S']`

Shortcut labels shown by the controls. See [keyboard shortcut configuration](/guide/toolbar#keyboard-shortcuts) to change actual key bindings.

---



# Table

Insert tables and edit their rows, columns, and cells.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, Table, RichTextTable, RichTextBubbleTable } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Table];

export default function TableExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextTable />
<RichTextBubbleTable />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import {
Table,
RichTextProvider,
RichTextTable,
RichTextBubbleTable,
} from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Table];

const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<RichTextTable />
<RichTextBubbleTable />
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

## How to use

The library’s `Table` includes row, header, cell, and cell-background extensions. Do not add duplicates. Click the toolbar grid to choose a table size, then select cells to use `RichTextBubbleTable`. You can also call `editor.chain().focus().insertTable({ rows: 3, cols: 3, withHeaderRow: true }).run()`.

## Leaving a table

A table is only as wide as its columns need, which leaves empty space beside and
under it. Clicking in that space puts the caret after the table rather than in
the nearest cell — without this, a click to the right of a table looks like the
caret is stuck inside it. An empty paragraph is inserted first when the table is
the last block or is followed by another table.

The context menu (right-click a cell) also has **Cell Background Color**: a palette plus a colour input that fills the selected cells through `setTableCellBackground(color)`; "No Fill" calls `unsetTableCellBackground()`.

The same move is available from the keyboard and from the table's context menu
(right-click a cell → "Paragraph After Table"), where the menu shows the
shortcut for the current platform:

| Platform | Shortcut |
| -------------- | -------------------------------- |
| macOS | <kbd>⌘</kbd> <kbd>Enter</kbd> |
| Windows, Linux | <kbd>Ctrl</kbd> <kbd>Enter</kbd> |

It is also a command, so a custom control can call it:

```ts
editor.chain().focus().insertParagraphAfterTable().run();
```

## Corners

The table's corners are `calc(var(--radius) - 2px)`, the same step down from
the editor's `--radius` that code blocks and menus use, so it matches the rest
of your UI. This needs `border-collapse: separate` (a collapsed table ignores
`border-radius`), which the stylesheet sets along with zeroed spacing and
one border edge per cell, so the grid looks the same as a collapsed one.

---



# TableOfContents

Track the headings of the document and insert a live table of contents block.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import {
RichTextProvider,
Heading,
TableOfContents,
RichTextTableOfContents,
} from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Heading, TableOfContents];

export default function TableOfContentsExample() {
const editor = useEditor({
extensions,
content: '<h1>Title</h1><p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextTableOfContents />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import {
Heading,
TableOfContents,
RichTextProvider,
RichTextTableOfContents,
} from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Heading, TableOfContents];

const editor = useEditor({
extensions,
content: '<h1>Title</h1><p>Try this feature here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<RichTextTableOfContents />
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

## How to use

`TableOfContents` does two things:

1. It watches every heading, gives each one a stable `id` / `data-toc-id` attribute and exposes the list through `editor.storage.tableOfContents.content`.
2. It registers the `tableOfContentsNode` block. Press the toolbar button or type `/toc` to insert it. The block re-renders whenever headings change, numbers entries hierarchically (`1`, `1.1`, `1.1.1`), highlights the heading currently in view, and scrolls to a heading when clicked.

The block is rendered as `<div data-type="table-of-contents"></div>` in the exported HTML; the list itself is generated at runtime from the headings.

## Insert from code

```ts
editor.chain().focus().insertTableOfContents().run();
```

## Render the outline outside the editor

Use the `useTableOfContents` hook to build a sidebar with the same data:

```tsx
import { useTableOfContents, scrollToTableOfContentsItem } from 'ai-sparkwrite-editor';

function Outline({ editor }) {
const items = useTableOfContents(editor);

return (
<ul>
{items.map((item) => (
<li key={item.id} style={{ paddingLeft: (item.level - 1) * 12 }}>
<button onClick={() => scrollToTableOfContentsItem(editor, item)}>
{item.textContent}
</button>
</li>
))}
</ul>
);
}
```

## Options

```ts
import { getLinearIndexes } from 'ai-sparkwrite-editor';

TableOfContents.configure({
// node types that count as headings (default: ['heading'])
anchorTypes: ['heading'],
// hierarchical numbering by default; use getLinearIndexes for 1, 2, 3…
getIndex: getLinearIndexes,
// generate stable ids instead of random uuids
getId: (text) => text.toLowerCase().replace(/\s+/g, '-'),
// element that scrolls, used to compute the active heading (default: window)
scrollParent: () => document.querySelector('.editor-scroll'),
HTMLAttributes: { class: 'table-of-contents' },
});
```

---



# Task List

Create a checklist with interactive checkboxes.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, TaskList, RichTextTaskList } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, TaskList];

export default function TaskListExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextTaskList />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { TaskList, RichTextProvider, RichTextTaskList } from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, TaskList];

const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<RichTextTaskList />
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

## How to use

The library’s `TaskList` includes `TaskItem`; do not register another task-item extension. Click the toolbar button to create a checklist and click a checkbox to change its checked state. Use `TaskList.configure({ taskItem: { nested: true } })` to allow nested tasks.

## Options

### shortcutKeys

Type: `string[]`\
Default: `['shift', 'mod', '9']`

Shortcut labels shown by the controls. See [keyboard shortcut configuration](/guide/toolbar#keyboard-shortcuts) to change actual key bindings.

---



# Text Align

Align supported text blocks to the left, center, right, or both margins.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, TextAlign, RichTextAlign } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, TextAlign];

export default function TextAlignExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextAlign />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { TextAlign, RichTextProvider, RichTextTextAlign } from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, TextAlign];

const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<RichTextTextAlign />
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

## How to use

Place the cursor in a paragraph and choose an alignment. Configure `types` with the node names you want to support, for example `TextAlign.configure({ types: ["paragraph", "heading"] })`. Register Heading as well if your document uses headings.

## Options

### shortcutKeys

Type: `string[][]`\
Default: `[['mod', 'shift', 'L'], ['mod', 'shift', 'E'], ['mod', 'shift', 'R'], ['mod', 'shift', 'J']]`

Shortcut labels shown by the controls. See [keyboard shortcut configuration](/guide/toolbar#keyboard-shortcuts) to change actual key bindings.

---



# Text Direction

Set the writing direction of text blocks for left-to-right or right-to-left content.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, TextDirection, RichTextTextDirection } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, TextDirection];

export default function TextDirectionExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
textDirection: 'auto',
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextTextDirection />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { TextDirection, RichTextProvider } from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, TextDirection];

const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

::: tip Vue
Not in the Vue layer yet: `RichTextTextDirection` — run the corresponding command from your own control, or see [Frameworks](/guide/frameworks).
:::

## How to use

The example sets `textDirection: "auto"` on `useEditor` so the direction control can also restore automatic direction. Direction determines writing order; use [Text Align](/extensions/TextAlign/) to change alignment.

---



# Underline

Underline selected text or text typed after enabling the mark.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, TextUnderline, RichTextUnderline } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, TextUnderline];

export default function TextUnderlineExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextUnderline />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { TextUnderline, RichTextProvider, RichTextUnderline } from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, TextUnderline];

const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<RichTextUnderline />
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

## How to use

Click the underline button to toggle the mark. For a custom button, use `editor.chain().focus().toggleUnderline().run()`.

## Options

### shortcutKeys

Type: `string[]`\
Default: `['mod', 'U']`

Shortcut labels shown by the controls. See [keyboard shortcut configuration](/guide/toolbar#keyboard-shortcuts) to change actual key bindings.

---



# Twitter

Embed a Twitter/X post in the document.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import {
RichTextProvider,
Twitter,
RichTextTwitter,
RichTextBubbleTwitter,
} from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

const extensions = [Document, Paragraph, Text, Twitter];

export default function TwitterExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextTwitter />
<RichTextBubbleTwitter />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

:::

::: warning React only
This feature's interactive UI depends on React libraries; the Vue layer does not include it yet. See [Frameworks](/guide/frameworks) for what the Vue entry covers.
:::

## How to use

Open the toolbar dialog and enter a supported post URL. Displaying the post depends on its availability and the embed service. Mount `RichTextBubbleTwitter` for contextual actions; a saved editor node does not archive the remote post.

---



# Video

Insert linked or uploaded videos into the document.

## Setup

Start with the packages in [Getting Started](/guide/getting-started). The complete example below registers the feature and renders its UI — pick the React or the Vue tab. In an existing editor, merge the imports and extension entries into your setup, and place the controls inside your existing `RichTextProvider`.

::: code-group

```tsx [React]
'use client';

import { EditorContent, useEditor } from '@tiptap/react';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { RichTextProvider, Video, RichTextVideo, RichTextBubbleVideo } from 'ai-sparkwrite-editor';
import 'ai-sparkwrite-editor/style.css';

function uploadVideo(
file: File,
onProgress?: (progress: { loaded: number; total: number }) => void
) {
return new Promise<string>((resolve, reject) => {
const formData = new FormData();
formData.append('file', file);

const request = new XMLHttpRequest();
request.open('POST', '/api/videos');
request.upload.addEventListener('progress', (event) => {
if (event.lengthComputable) {
onProgress?.({ loaded: event.loaded, total: event.total });
}
});
request.addEventListener('load', () => {
if (request.status < 200 || request.status >= 300) {
reject(new Error('Video upload failed'));
return;
}

try {
const data = JSON.parse(request.responseText);
if (typeof data.url !== 'string' || !data.url) {
throw new Error('Upload response must contain a video URL');
}
resolve(data.url);
} catch (error) {
reject(error);
}
});
request.addEventListener('error', () => reject(new Error('Video upload failed')));
request.send(formData);
});
}

const extensions = [
Document,
Paragraph,
Text,
Video.configure({
resourceVideo: 'both',
acceptMimes: ['video/mp4', 'video/webm'],
maxSize: 100 * 1024 * 1024,
multiple: true,
uploadConcurrency: 3,
showUploadProgress: true,
upload: (file, { onProgress } = {}) => uploadVideo(file, onProgress),
onError: ({ message, file }) => {
console.error(message, file?.name);
},
}),
];

export default function VideoExample() {
const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
immediatelyRender: false,
});

if (!editor) return null;

return (
<RichTextProvider editor={editor}>
<RichTextVideo />
<RichTextBubbleVideo />
<EditorContent editor={editor} />
</RichTextProvider>
);
}
```

```vue [Vue]
<script setup lang="ts">
import { EditorContent, useEditor } from '@tiptap/vue-3';
import { Document } from '@tiptap/extension-document';
import { Paragraph } from '@tiptap/extension-paragraph';
import { Text } from '@tiptap/extension-text';
import { Video, RichTextProvider, RichTextVideo } from 'ai-sparkwrite-editor/vue';
import 'ai-sparkwrite-editor/style.css';

function uploadVideo(
file: File,
onProgress?: (progress: { loaded: number; total: number }) => void
) {
return new Promise<string>((resolve, reject) => {
const formData = new FormData();
formData.append('file', file);

const request = new XMLHttpRequest();
request.open('POST', '/api/videos');
request.upload.addEventListener('progress', (event) => {
if (event.lengthComputable) {
onProgress?.({ loaded: event.loaded, total: event.total });
}
});
request.addEventListener('load', () => {
if (request.status < 200 || request.status >= 300) {
reject(new Error('Video upload failed'));
return;
}

try {
const data = JSON.parse(request.responseText);
if (typeof data.url !== 'string' || !data.url) {
throw new Error('Upload response must contain a video URL');
}
resolve(data.url);
} catch (error) {
reject(error);
}
});
request.addEventListener('error', () => reject(new Error('Video upload failed')));
request.send(formData);
});
}

const extensions = [
Document,
Paragraph,
Text,
Video.configure({
resourceVideo: 'both',
acceptMimes: ['video/mp4', 'video/webm'],
maxSize: 100 * 1024 * 1024,
multiple: true,
uploadConcurrency: 3,
showUploadProgress: true,
upload: (file, { onProgress } = {}) => uploadVideo(file, onProgress),
onError: ({ message, file }) => {
console.error(message, file?.name);
},
}),
];

const editor = useEditor({
extensions,
content: '<p>Try this feature here.</p>',
});
</script>

<template>
<RichTextProvider :editor="editor">
<RichTextVideo />
<EditorContent :editor="editor" />
</RichTextProvider>
</template>
```

:::

::: tip Vue
Not in the Vue layer yet: `RichTextBubbleVideo` — run the corresponding command from your own control, or see [Frameworks](/guide/frameworks).
:::

## How to use

The upload example calls your application’s `/api/videos` endpoint, which must return JSON containing a `url` string. For URL-only use without a backend, replace the configuration with `Video.configure({ resourceVideo: "link" })`. Mount `RichTextBubbleVideo` for contextual controls. A hosting provider must permit embedding for its player to work.

## Props

```ts
interface VideoUploadProgress {
loaded: number;
total: number;
}

interface VideoUploadContext {
onProgress?: (progress: VideoUploadProgress) => void;
}

interface VideoOptions extends GeneralOptions<VideoOptions> {
/**
* Indicates whether fullscreen play is allowed
*
* @default true
*/
allowFullscreen: boolean;
/**
* Indicates whether to display the frameborder
*
* @default false
*/
frameborder: boolean;
/**
* Width of the video, can be a number or string
*
* @default VIDEO_SIZE['size-medium']
*/
width: number | string;
/** HTML attributes object for passing additional attributes */
HTMLAttributes: {
[key: string]: any;
};
/** Function for uploading files */
upload?: (file: File, context?: VideoUploadContext) => Promise<string>;

/** Whether multiple videos can be selected and uploaded at once */
multiple?: boolean;

/** Maximum number of videos uploaded concurrently */
uploadConcurrency?: number;

/**
* Whether to display overall and per-file upload progress
*
* @default true
*/
showUploadProgress?: boolean;

/** Accepted video MIME types or file extensions */
acceptMimes?: string[];

/** Maximum size of a single video in bytes. No limit is applied when omitted. */
maxSize?: number;

/** Callback invoked when video validation or upload fails */
onError?: (error: { type: 'size' | 'type' | 'upload'; message: string; file?: File }) => void;

/** The source URL of the video */
resourceVideo: 'upload' | 'link' | 'both';

/**
* List of allowed video hosting providers.
* Use ['.'] to allow any URL.
*
* @default ['.']
*/
videoProviders?: string[];
}
```

## Options

| Option | Type | Description | Required | Default |
| -------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -------- | ----------------------------- |
| `allowFullscreen` | `boolean` | Allows embedded videos to enter fullscreen mode. | No | `true` |
| `frameborder` | `boolean` | Displays a border around the embedded video frame. | No | `false` |
| `width` | `number \| string` | Sets the default video width. | No | `VIDEO_SIZE.size-medium` |
| `HTMLAttributes` | `Record<string, any>` | Adds HTML attributes to the video wrapper. | No | `{ class: 'iframe-wrapper' }` |
| `upload` | `(file: File, context?: VideoUploadContext) => Promise<string>` | Uploads a local video, optionally reports byte progress, and resolves with its URL. | No | None |
| `multiple` | `boolean` | Allows selecting and uploading multiple videos. | No | `true` |
| `uploadConcurrency` | `number` | Limits the number of videos uploaded at the same time. Values below `1` are treated as `1`. | No | `3` |
| `showUploadProgress` | `boolean` | Displays overall and per-file progress when byte progress is reported. | No | `true` |
| `acceptMimes` | `string[]` | Restricts local files by MIME type or extension; wildcard values such as `video/*` are supported. | No | `['video/*']` |
| `maxSize` | `number` | Maximum size of each local video in bytes. No size limit is applied when omitted. | No | None |
| `onError` | `(error: { type: 'size' \| 'type' \| 'upload'; message: string; file?: File }) => void` | Handles validation and upload failures. When omitted, the editor displays its default error toast. | No | None |
| `resourceVideo` | `'upload' \| 'link' \| 'both'` | Controls whether users can add videos by local upload, URL, or both. | No | `'both'` |
| `videoProviders` | `string[]` | Restricts linked videos to matching providers. Use `['.']` to accept any URL. | No | `['.']` |

## Upload behavior

The `XMLHttpRequest` example reports uploaded bytes through `onProgress`. A plain `fetch` upload does not provide that byte-progress callback.

While the `upload` promise is pending, both the toolbar dialog and the slash-command dialog stay
open and disable the upload button. Call `context.onProgress({ loaded, total })` to show real,
byte-weighted total progress and per-file progress. If an existing upload function ignores the
optional second argument, it remains compatible and the editor shows an indeterminate spinner.
Progress details are enabled by default. Set `showUploadProgress: false` to hide the overall and
per-file progress UI while keeping the disabled upload button and indeterminate loading indicator.

When all uploads resolve, their URLs are inserted in selection order and the dialog closes. A file
that reaches 100% before its upload promise resolves is shown as processing.

If one upload rejects, other successful videos are still inserted. The failed file remains marked in
the open dialog so the user can select it again. Configure `onError` to provide custom error handling;
otherwise, the editor shows its default upload error toast.

`acceptMimes` and `maxSize` validate every selected file before uploading. With `multiple: true`, all
valid files are queued and up to `uploadConcurrency` files upload at once.}}