# DOCX Editor — full documentation

This file contains the complete docs for the @eigenpal/docx-editor-* packages, concatenated and stripped of HTML/frontmatter so an LLM can ingest it in one shot.

Source of truth: https://www.docx-editor.dev/docs/1.x
Generated from: src/content/docs/*.mdx (23 files)

---

# Agents. Bring your own agent

Source: https://www.docx-editor.dev/docs/1.x/agents/bring-your-own

## Tool schemas

All 14 tools ship as OpenAI-style function definitions. Anything that accepts that shape. Vercel AI SDK, Anthropic's tool use, OpenAI Assistants, LangChain, takes them as-is.

```ts
import { getToolSchemas } from "@eigenpal/docx-editor-agents";

const schemas = getToolSchemas();
// [{ name: "add_comment", description: "...", parameters: { ... } }, ...]
```

## Vercel AI SDK

The shortest path. Use the AI SDK subpath:

```ts
// server
import { streamText } from "ai";
import { getAiSdkTools } from "@eigenpal/docx-editor-agents/ai-sdk/server";

export async function POST(req: Request) {
  const { messages, tools: clientTools } = await req.json();
  return streamText({
    model: "openai/gpt-4o",
    messages,
    tools: getAiSdkTools(clientTools),
  }).toUIMessageStreamResponse();
}
```

```tsx
// client
import { useChat } from "@ai-sdk/react";
import { useDocxAgentTools } from "@eigenpal/docx-editor-agents/react";
import { toAgentMessages } from "@eigenpal/docx-editor-agents/ai-sdk/react";

const { tools } = useDocxAgentTools({ editorRef });
const chat = useChat({ api: "/api/agent-chat", body: { tools } });
const agentMessages = toAgentMessages(chat.messages);
```

## Anthropic (Claude)

Use the tool schemas with the Anthropic SDK's `tool_use` blocks.

```ts
import Anthropic from "@anthropic-ai/sdk";
import { getToolSchemas, executeToolCall } from "@eigenpal/docx-editor-agents";

const client = new Anthropic();
const schemas = getToolSchemas();

const response = await client.messages.create({
  model: "claude-sonnet-4-7",
  max_tokens: 1024,
  tools: schemas.map(toAnthropicTool),
  messages: [/* ... */],
});

// On tool_use blocks, dispatch to executeToolCall against your DocxReviewer instance.
```

## OpenAI

Same schemas, same shape, just pass them to `tools:` in the chat completions API.

## MCP clients

If your agent already speaks MCP, expose the toolkit as a server instead:

```ts
import { McpServer } from "@eigenpal/docx-editor-agents/mcp";

const server = new McpServer(reviewer);
// wire to your MCP transport (stdio, websocket, etc.)
```

See the [API reference: agents](/docs/1.x/api/agents) for full signatures.

## LangChain / custom

`agentTools` is the underlying tool definition array. Wrap each entry however your framework expects.

```ts
import { agentTools, executeToolCall } from "@eigenpal/docx-editor-agents";

for (const tool of agentTools) {
  // Convert to your framework's tool shape...
}

// When the framework dispatches a tool call:
const result = await executeToolCall(reviewerOrBridge, toolName, toolInput);
```

## Where to go next

- [Live editor](/docs/1.x/agents/live-editor), full client wiring
- [Word JS API parity](/docs/1.x/agents/word-js-api), the Office.js mapping
- [API reference](/docs/1.x/api/agents), every subpath

---

# 1.x/agents/index

Source: https://www.docx-editor.dev/docs/1.x/agents/index

<PackageStats name="@eigenpal/docx-editor-agents" />

## What's in it

14 document-editing tools, three transports. Same tool shapes everywhere; pick the transport that fits where the agent runs.

| Transport | API | Use case |
|---|---|---|
| **Live editor** | `useDocxAgentTools` (React or Vue) | Agent calls land on a `<DocxEditor>` running in a user's browser. Comments and tracked changes show up as they happen. |
| **Headless** | `DocxReviewer` (Node) | Server-side batch. Parse buffer, run the agent, get the modified buffer back. No DOM. |
| **MCP** | `McpServer` | Expose the tool catalog over JSON-RPC. Any MCP-compatible client can drive it. |

```bash
npm install @eigenpal/docx-editor-agents
```


## Subpaths

- `@eigenpal/docx-editor-agents`: `DocxReviewer`, `agentTools`, `getToolSchemas`, `executeToolCall`
- `@eigenpal/docx-editor-agents/react`: `useDocxAgentTools`, `useAgentChat`, `getToolDisplayName`
- `@eigenpal/docx-editor-agents/vue`: Vue composables matching the React hooks
- `@eigenpal/docx-editor-agents/server`: server-side types
- `@eigenpal/docx-editor-agents/ai-sdk/server`: `getAiSdkTools()` for Vercel AI SDK `streamText`
- `@eigenpal/docx-editor-agents/ai-sdk/react`: `toAgentMessages()` to bridge AI SDK `UIMessage[]` into `<AgentChatLog>` shape
- `@eigenpal/docx-editor-agents/bridge`: lower-level transport for non-React hosts
- `@eigenpal/docx-editor-agents/mcp`: `McpServer` for MCP integration

Full surface in the [API reference for `@eigenpal/docx-editor-agents`](/docs/1.x/api/agents).

## The 14 tools

- **Locate (7):** `read_document`, `read_selection`, `read_page`, `read_pages`, `find_text`, `read_comments`, `read_changes`
- **Mutate (6):** `add_comment`, `suggest_change`, `apply_formatting`, `set_paragraph_style`, `reply_comment`, `resolve_comment`
- **Navigate (1):** `scroll`

Locate-then-mutate. Locate tools return paragraphs tagged with `paraId` (Word's built-in `w14:paraId` attribute); mutate tools take `paraId` as input. `paraId` survives concurrent edits, agent loop iterations, and tool calls. So an agent can `find_text` in turn 1 and `add_comment` on the same paragraph in turn 5 without re-resolving.

## Where to next

- [Live editor](/docs/1.x/agents/live-editor), wire `useDocxAgentTools` + AI SDK into a `<DocxEditor>`
- [Bring your own agent](/docs/1.x/agents/bring-your-own): Vercel AI SDK, OpenAI, Anthropic, LangChain
- [Word JS API parity](/docs/1.x/agents/word-js-api): Office.js verb mapping, compile-time-enforced
- [API reference](/docs/1.x/api/agents)

---

# Agents. Live editor

Source: https://www.docx-editor.dev/docs/1.x/agents/live-editor

## What it is

Live editor mode runs the agent against a `<DocxEditor>` instance in the user's browser. Tool calls turn into real comments, tracked changes, and scroll actions on the document the user is looking at. No server-side review job, no buffer round-trip. The user sees the agent's tool calls land as the model streams tokens.

```bash
npm install @eigenpal/docx-editor-react @eigenpal/docx-editor-agents
```

## Minimal wiring

```tsx
"use client";

import { useRef } from "react";
import { DocxEditor, type DocxEditorRef } from "@eigenpal/docx-editor-react";
import { useDocxAgentTools } from "@eigenpal/docx-editor-agents/react";
import { useChat } from "@ai-sdk/react";

export function EditorWithAgent({ documentBuffer }: { documentBuffer: ArrayBuffer }) {
  const editorRef = useRef<DocxEditorRef>(null);
  const { tools } = useDocxAgentTools({ editorRef });

  const { messages, sendMessage } = useChat({
    api: "/api/agent-chat",
    body: { tools },
  });

  return (
    <div>
      <DocxEditor ref={editorRef} documentBuffer={documentBuffer} />
      {/* render messages, sendMessage button, etc. */}
    </div>
  );
}
```

`useDocxAgentTools` returns tool definitions the AI SDK consumes; the call lifecycle is forwarded transparently. Server side, wrap the client's tool descriptors with `getAiSdkTools()`:

```ts
// app/api/agent-chat/route.ts
import { streamText } from "ai";
import { getAiSdkTools } from "@eigenpal/docx-editor-agents/ai-sdk/server";

export async function POST(req: Request) {
  const { messages, tools: clientTools } = await req.json();
  const tools = getAiSdkTools(clientTools);
  return streamText({ model: "openai/gpt-4o", messages, tools }).toUIMessageStreamResponse();
}
```

## Tool call lifecycle

1. Model decides to call a tool (e.g. `add_comment`).
2. AI SDK forwards the call to the client.
3. `useDocxAgentTools` executes against the live editor via `editorRef`.
4. The editor renders the change (comment marker, tracked-change underline).
5. Tool result returns to the model on the next turn.

`paraId` is the trick that makes multi-turn work cleanly. The agent can `find_text` in turn 1 and `add_comment` on the same paragraph in turn 5 without re-resolving, because `paraId` is Word's stable `w14:paraId` attribute and survives concurrent edits.

## Agent UI primitives

The chat surfaces ship with the toolkit, not the editor:

```tsx
import {
  AgentPanel,
  AgentChatLog,
  AgentComposer,
  AgentSuggestionChip,
  AgentTimeline,
} from "@eigenpal/docx-editor-agents/react";
```

Same for Vue: `@eigenpal/docx-editor-agents/vue`. The hooks don't care what UI you wire up, so bring your own if you prefer.

## Where to next

- [Bring your own agent](/docs/1.x/agents/bring-your-own): Vercel AI SDK, OpenAI, Anthropic, LangChain
- [agents/react API reference](/docs/1.x/api/agents/react), full hook signatures
- [Word JS API parity](/docs/1.x/agents/word-js-api): Office.js verb mapping

---

# Agents. Word JS API parity

Source: https://www.docx-editor.dev/docs/1.x/agents/word-js-api

## Why parity matters

The toolkit shadows the shape of Microsoft's Office.js Word API on purpose. If your model has been trained on Office.js examples, it picks up our tools without re-prompting. If you're migrating a Word add-in, the rename map below is the only diff.

`WordCompatBridge` is a TypeScript type alias that formally documents every method we mirror. A compile-time static assertion fails the build if a method goes out of sync.

## Verb map

| Office.js | DOCX Editor toolkit | Notes |
|---|---|---|
| `Range.insertComment(text)` | `addComment({ paraId, text })` | We address by stable `paraId`, not by `Range`. |
| `Body.search(query)` | `findText({ query })` | Returns paragraphs with `paraId`s. |
| `Comment.reply(text)` | `replyComment({ commentId, text })` | |
| `Comment.resolved = true` | `resolveComment({ commentId })` | |
| `Range.scrollIntoView()` | `scroll({ paraId })` | |
| `Range.insertText(text, location)` | `suggestChange({ paraId, ... })` | Inserts as a tracked change. |
| `Range.font.bold = true` | `applyFormatting({ paraId, bold: true })` | |
| `Range.paragraphFormat.styleName = "Heading 1"` | `setParagraphStyle({ paraId, style: "Heading1" })` | |

## Addressing model

Office.js uses `Range` objects that are live and tied to a document model. JSON-RPC tool transports can't ferry live objects, they need a string ID that survives serialization, network round-trips, and concurrent edits.

The toolkit uses Word's `w14:paraId` attribute. Every paragraph in a Word-authored `.docx` has one. They're stable across edits, concurrent collaboration, and tool loop iterations. `read_document` returns paragraphs tagged with their `paraId`; every mutate tool takes a `paraId` as input.

## Migrating a Word add-in

1. Replace `Word.run(async (context) => { ... })` with a `DocxReviewer.fromBuffer(buffer)` (headless) or `useDocxAgentTools({ editorRef })` (live editor) wiring.
2. Replace `Range`-based addressing with `paraId`-based addressing. Use `findText` or `read_document` to resolve a paragraph first.
3. Replace each Office.js method call with its tool equivalent from the table above.

For agents you're writing fresh, you don't need this mapping at all, just call the tools directly.

## Where to go next

- [Tool catalog](/docs/1.x/api/agents), full schemas
- [Live editor](/docs/1.x/agents/live-editor), wire to a `<DocxEditor>`
- [Bring your own agent](/docs/1.x/agents/bring-your-own), provider adapters

---

# 1.x/core/index

Source: https://www.docx-editor.dev/docs/1.x/core/index

<PackageStats name="@eigenpal/docx-editor-core" />

## What's in it

The document tree, the OOXML parser and serializer, the ProseMirror schema, layout primitives, the plugin contract. No DOM, no framework. The React and Vue adapters depend on it. You install `-core` directly only when you don't want an editor UI on the page.

```bash
npm install @eigenpal/docx-editor-core
```

## When to use it directly

- Server-side `.docx` processing: parse buffer, walk the tree, mutate, serialize back out.
- Headless extraction: pull text, tables, headers/footers without rendering.
- Custom renderer or DOM bridge against the shared schema.
- Plugins that need to work in React, Vue, and headless contexts. Use the `core-plugins` subpath.

If you want an actual editor in a React or Vue app, install `@eigenpal/docx-editor-react` or `@eigenpal/docx-editor-vue`. Both pull `-core` in transitively, so you don't need it as a separate dep.

## Subpaths

61 published subpaths. The ones you'll touch most:

- `@eigenpal/docx-editor-core`: root barrel
- `@eigenpal/docx-editor-core/docx-parser`: `parseDocx(buffer)` → `Document` tree
- `@eigenpal/docx-editor-core/docx-serializer`: `Document` → `.docx` buffer
- `@eigenpal/docx-editor-core/types`: `Document`, `Paragraph`, `Run`, `Insertion`, `Deletion`, `Comment`
- `@eigenpal/docx-editor-core/core-plugins`: plugin contract for non-React, non-Vue hosts
- `@eigenpal/docx-editor-core/headless`: bridge-shaped APIs (no DOM)

All 61 are in the [API reference](/docs/1.x/api/core).

## Parse, mutate, serialize

```ts
import { parseDocx } from "@eigenpal/docx-editor-core/docx-parser";
import { serializeDocx } from "@eigenpal/docx-editor-core/docx-serializer";

const buffer = await fetch("./document.docx").then((r) => r.arrayBuffer());
const tree = await parseDocx(buffer);

for (const para of tree.body) {
  if (para.type === "paragraph") {
    console.log(para.paraId, para.runs.map((r) => r.text).join(""));
  }
}

const out = await serializeDocx(tree);
```

The tree shape is the same the editor renders against. Anything you build against `-core` ports without translation when the same buffer reaches the live editor.

## Content controls

Block-level content controls (Word's `w:sdt`) are addressable by tag, alias, id, or type. `findContentControls` lists the matches and `findContentControl` returns one; each carries its text plus modeled state (`showingPlaceholder`, `checked`, `dateFormat`, `listItems`, `dataBinding`). `setContentControlContent` fills a control with a string or block content, `setContentControlValue` sets a typed value (dropdown selection, checkbox, date), and `removeContentControl` deletes or unwraps one.

```ts
import { findContentControls, setContentControlValue } from "@eigenpal/docx-editor-core/headless";

const boxes = findContentControls(tree, { type: "checkbox" });
setContentControlValue(tree, { tag: "agreed" }, true);
```

Edits preserve the control's identity and raw properties, so the document still round-trips. Locked and typed controls are refused unless you force them. That stability is what makes content controls usable as anchors for templates and document automation. Repeating sections (`w15:repeatingSection`) round-trip the same way: `addRepeatingSectionItem` clones an item with fresh ids and `removeRepeatingSectionItem` drops one.

## Where to next

- [API reference (61 subpaths)](/docs/1.x/api/core)
- [Plugins](/docs/1.x/plugins) for the plugin contract
- [`@eigenpal/docx-editor-agents`](/docs/1.x/agents): `DocxReviewer` wraps `-core` for AI-driven document review

---

# Interactive Examples

Source: https://www.docx-editor.dev/docs/1.x/examples

## Playground

Try the full interactive playground to toggle props and see changes immediately:

<DemoPlayground />

## Read-Only Mode

Compare the full editor with a read-only preview. The `readOnly` prop strips the toolbar and all editing UI:

<ReadOnlyDemo />

## Mode Toggle

Switch between editing, suggesting, and viewing modes to see how the editor behaves in each:

<ModeToggleDemo />

## Toolbar Customization

Customize the title bar with a logo, document name, and right-side actions:

<ToolbarCustomDemo />

## Author Attribution

Set the `author` prop to attribute comments and track changes to specific users:

<AuthorDemo />

## Agent Chat in the Editor

Added in 0.2.0. Wire `<DocxEditor>` to the agent UI kit ([`<AgentPanel>`, `<AgentChatLog>`, `<AgentComposer>`](/docs/1.x/react)) and a chat backend in one component. The agent reads paragraphs, adds comments, suggests tracked changes, and scrolls while the user watches.

<AgentChatDemo />

The full client + server snippet is on the [Live editor page](/docs/1.x/agents/live-editor). For OpenAI, Anthropic, and Vercel AI SDK adapters see [Bring your own agent](/docs/1.x/agents/bring-your-own). Runnable Next.js example: [agent-chat-demo on GitHub](https://github.com/eigenpal/docx-editor/tree/main/examples/agent-chat-demo).

For the server-side flavor (no editor, batch review) see [Headless](/docs/1.x/agents) and [MCP server](/docs/1.x/agents).

---

# 1.x/i18n/index

Source: https://www.docx-editor.dev/docs/1.x/i18n/index

<PackageStats name="@eigenpal/docx-editor-i18n" />

## Why the split

In 0.x, locales lived inside `@eigenpal/docx-js-editor` at `/i18n/<code>.json`. With a Vue adapter joining React in 1.0, that path would have meant duplicating the same JSON in two places. `-i18n` extracts it to a standalone package both adapters depend on.

```bash
npm install @eigenpal/docx-editor-i18n
```

You usually don't install this directly. `-react` and `-vue` pull it in transitively. Install it explicitly only when you're using the locale data outside the editor (a custom toolbar, a search dropdown, that kind of thing).

## Available locales

| Code | Language | Named export |
|---|---|---|
| `en` | English | `en` |
| `pl` | Polish | `pl` |
| `de` | German | `de` |
| `fr` | French | `fr` |
| `pt-BR` | Brazilian Portuguese | `ptBR` |
| `he` | Hebrew | `he` |
| `hi` | Hindi | `hi` |
| `tr` | Turkish | `tr` |
| `zh-CN` | Chinese (Simplified) | `zhCN` |

Two import shapes are supported in 1.0.1+:

- **Named exports off the root** (`import { pl } from "@eigenpal/docx-editor-i18n"`). Use this when you ship a small static list of locales.
- **Per-locale subpath imports** (`import pl from "@eigenpal/docx-editor-i18n/pl"`). Use this when you dynamically load locales; the per-locale subpath code-splits so users only download the language they need.

The 0.x `import pl from "@eigenpal/docx-js-editor/i18n/pl.json"` JSON pattern is gone, but the new subpath form covers the same use case. See the [migration guide](/docs/1.x/migration#i18n-restructure) for the rewrite.

Verify what your installed version ships:

```bash
ls node_modules/@eigenpal/docx-editor-i18n/
```

To contribute a locale, PR the JSON to `packages/i18n/<code>.json` upstream.

## Importing

Named exports off the package root:

```ts
import { en, pl, de, ptBR } from "@eigenpal/docx-editor-i18n";
```

Hyphenated codes (`pt-BR`, `zh-CN`) become camelCase named exports (`ptBR`, `zhCN`).

## Wiring into the editor

Pass the locale object to the `i18n` prop. React:

```tsx
import { DocxEditor } from "@eigenpal/docx-editor-react";
import { pl } from "@eigenpal/docx-editor-i18n";

<DocxEditor documentBuffer={buf} i18n={pl} />;
```

Vue:

```vue
<script setup>
import { DocxEditor } from "@eigenpal/docx-editor-vue";
import { pl } from "@eigenpal/docx-editor-i18n";
</script>

<template>
  <DocxEditor :document-buffer="buf" :i18n="pl" />
</template>
```

## Where to next

- [i18n API reference](/docs/1.x/api/i18n)
- [React API reference: i18n prop](/docs/1.x/api/react)
- [Migration: i18n restructure](/docs/1.x/migration#i18n-restructure)

---

# 1.x/index

Source: https://www.docx-editor.dev/docs/1.x/index

## Packages

| Package | What's in it |
|---|---|
| [`@eigenpal/docx-editor-core`](/docs/1.x/api/core) | Document tree, OOXML parser/serializer, ProseMirror schema. Framework-agnostic. The React and Vue adapters depend on this. |
| [`@eigenpal/docx-editor-react`](/docs/1.x/api/react) | `<DocxEditor>` plus hooks for history, find/replace, autosave, clipboard. Toolbar, dialogs, plugin host. |
| [`@eigenpal/docx-editor-vue`](/docs/1.x/api/vue) | Vue 3 adapter. Same `<DocxEditor>`, hooks become composables. Beta in 1.0. |
| [`@eigenpal/docx-editor-agents`](/docs/1.x/api/agents) | `DocxReviewer` (headless), live-editor bridge, AI SDK adapters, MCP server. 14 tools. |
| [`@eigenpal/docx-editor-i18n`](/docs/1.x/api/i18n) | Locale data. Ships `en`, `pl`, `de`, `pt-BR`, `he`, `tr`, `zh-CN`. |

All five are Apache 2.0. The agents package was AGPL-3.0 in 0.x; see the [migration guide](/docs/1.x/migration) if you tracked the license.

## Which package do I need?

**React app.** Install `-react`. It pulls in `-core` and `-i18n`.

```bash
npm install @eigenpal/docx-editor-react
```

**Vue 3 app.** Same shape, swap the adapter.

```bash
npm install @eigenpal/docx-editor-vue
```

**Server-side parsing or batch review.** Use `-core` for the document tree and `-agents` for `DocxReviewer`.

```bash
npm install @eigenpal/docx-editor-core @eigenpal/docx-editor-agents
```

**Add an AI agent to an existing editor.** Layer `-agents` on top of `-react` or `-vue`.

```bash
npm install @eigenpal/docx-editor-agents
```

**Expose tools over MCP.** Same install. The MCP server is the `/mcp` subpath of `-agents`.

## Render an editor (React)

```tsx
import { DocxEditor } from "@eigenpal/docx-editor-react";
import "@eigenpal/docx-editor-react/styles.css";

export default function App() {
  return <DocxEditor documentBuffer={null} />;
}
```

`documentBuffer={null}` mounts an empty document. Pass an `ArrayBuffer` to load a `.docx`. See [Installation](/docs/1.x/installation) for Next.js, Vite, Remix, Astro, Vue specifics.

## Where to next

- [Installation](/docs/1.x/installation), per-framework setup
- [Migration: 0.x → 1.x](/docs/1.x/migration)
- [API reference](/docs/1.x/api), every published subpath, generated from the d.ts
- [Realtime collaboration](/docs/1.x/realtime-collaboration): Yjs
- [Plugins](/docs/1.x/plugins)
- [Examples](/docs/1.x/examples), interactive demos

---

# Installation

Source: https://www.docx-editor.dev/docs/1.x/installation

## Pick a package

Five packages, install what you need. The framework adapters pull `-core` and `-i18n` in transitively, so for most apps it's one install.

```bash
# React
npm install @eigenpal/docx-editor-react

# Vue 3
npm install @eigenpal/docx-editor-vue

# Headless / server-side (no UI)
npm install @eigenpal/docx-editor-core

# Agent toolkit (layer on top of an adapter)
npm install @eigenpal/docx-editor-agents
```

## React frameworks

### Next.js (App Router)

ProseMirror touches the DOM at mount, so the editor renders client-side. Mark the file `"use client"`:

```tsx
// app/editor/page.tsx
"use client";

import { DocxEditor } from "@eigenpal/docx-editor-react";
import "@eigenpal/docx-editor-react/styles.css";

export default function Page() {
  return <DocxEditor documentBuffer={null} />;
}
```

Wrap the page in a server component if you want the chrome (nav, footer) to SSR; only the editor itself needs `"use client"`. React 19 + Next 15+: no extra config.

Runnable example: [`examples/nextjs`](https://github.com/eigenpal/docx-editor/tree/main/examples/nextjs).

### Vite

Vite is plain client-rendered React. No SSR caveat.

```tsx
// src/App.tsx
import { DocxEditor } from "@eigenpal/docx-editor-react";
import "@eigenpal/docx-editor-react/styles.css";

export default function App() {
  return <DocxEditor documentBuffer={null} />;
}
```

Runnable example: [`examples/vite`](https://github.com/eigenpal/docx-editor/tree/main/examples/vite).

### Remix

Same constraint as Next. Render the editor inside a route module client-side, or use Remix's `<ClientOnly>` helper.

Runnable example: [`examples/remix`](https://github.com/eigenpal/docx-editor/tree/main/examples/remix).

### Astro

React island with `client:only="react"`:

```astro
---
import EditorIsland from "./EditorIsland.tsx";
---
<EditorIsland client:only="react" />
```

`client:only` skips Astro's SSR step for the island, which is what you want here.

Runnable example: [`examples/astro`](https://github.com/eigenpal/docx-editor/tree/main/examples/astro).

## Vue 3

```vue
<script setup lang="ts">
import { DocxEditor } from "@eigenpal/docx-editor-vue";
import "@eigenpal/docx-editor-vue/styles.css";
</script>

<template>
  <DocxEditor :document-buffer="null" />
</template>
```

Same props as React, same dialogs, same plugin API. See the [Vue page](/docs/1.x/vue) for the parity contract.

Runnable example: [`examples/vue`](https://github.com/eigenpal/docx-editor/tree/main/examples/vue).

### Nuxt

On Nuxt, install the official module `@eigenpal/nuxt-docx-editor` instead of wiring the adapter by hand. It registers an SSR-safe `<DocxEditor>` as an auto-imported component, so there's no manual import and no `<ClientOnly>` wrapper.

```bash
npm install @eigenpal/nuxt-docx-editor
```

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ["@eigenpal/nuxt-docx-editor"],
});
```

```vue
<!-- pages/editor.vue -->
<template>
  <DocxEditor :document-buffer="null" />
</template>
```

The module wraps `@eigenpal/docx-editor-vue` (a transitive dependency), adds its stylesheet to Nuxt's CSS pipeline, and registers `<DocxEditor>` as a client-only component. Works on Nuxt 3 and 4. See the [Nuxt module page](/docs/1.x/vue/nuxt) for options and auto-imported composables.

Runnable example: [`examples/nuxt`](https://github.com/eigenpal/docx-editor/tree/main/examples/nuxt).

## Headless / Node

Skip the adapter when you don't need an editor on the page:

```ts
import { parseDocx, serializeDocx } from "@eigenpal/docx-editor-core";

const tree = await parseDocx(buffer);
// ...mutate the tree...
const outBuffer = await serializeDocx(tree);
```

For server-side AI review, layer `@eigenpal/docx-editor-agents` on top:

```ts
import { DocxReviewer } from "@eigenpal/docx-editor-agents";

const reviewer = await DocxReviewer.fromBuffer(buffer);
await reviewer.addComment({ paraId: "...", text: "..." });
```

## CSS

Each adapter ships a CSS bundle at `<pkg>/styles.css`. Import once:

```ts
import "@eigenpal/docx-editor-react/styles.css";
// or
import "@eigenpal/docx-editor-vue/styles.css";
```

The editor's styles are scoped (`.docx-editor-root` and below), so they don't collide with Tailwind utilities or your app's CSS.

## Next steps

- [Migration: 0.x → 1.x](/docs/1.x/migration)
- [React API reference](/docs/1.x/api/react)
- [Vue API reference](/docs/1.x/api/vue)
- [Agents](/docs/1.x/agents) for AI integration

---

# Migration: 0.x → 1.x

Source: https://www.docx-editor.dev/docs/1.x/migration

## What moved where

0.x was a single package. 1.x splits it into five, by concern:

| What you used in 0.x | Where it is in 1.x |
|---|---|
| The `<DocxEditor>` component, toolbar, dialogs, hooks, plugin host | `@eigenpal/docx-editor-react` (or `@eigenpal/docx-editor-vue`) |
| The document model and OOXML parse/serialize (`Document`, `Paragraph`, `createEmptyDocument`, ...) | `@eigenpal/docx-editor-core` |
| Anything AI: the reviewer, agent UI components, the MCP server | `@eigenpal/docx-editor-agents` |
| Locale strings (`pl`, `de`, `pt-BR`, ...) | `@eigenpal/docx-editor-i18n` |

In practice a React app still imports from one package, `@eigenpal/docx-editor-react`, which pulls in `-core` and `-i18n` for you. You only name the other packages when you import the document model, the agent toolkit, or locale data directly. The rest of this guide is the symbol-level detail behind that split.

## TL;DR

1. Install the new package set (`-react` or `-vue`, plus `-core` and `-agents` if you need them).
2. **Update the symbols whose home changed across packages first** (see [Moved symbols](#moved-symbols)), a plain package-name swap leaves them unresolved.
3. Change every remaining `@eigenpal/docx-js-editor` import to `@eigenpal/docx-editor-react`.
4. Rename `FormattingBar` → `Toolbar` and `Toolbar` (composite) → `EditorToolbar`.
5. Remove `showPrintButton` from `<DocxEditor>` and toolbar props (deleted in 1.0).
6. Rewire i18n imports, locales are **named exports** now, not subpath JSON files.
7. License changes: every package is now Apache 2.0 (the agents package was AGPL-3.0).

The mechanical work is small but the moved symbols catch people. Read [Moved symbols](#moved-symbols) before you start updating imports.

## Package renames

The monolithic `@eigenpal/docx-js-editor` split into five packages under the `@eigenpal/docx-editor-*` namespace.

| Old (0.x) | New (1.x) |
|---|---|
| `@eigenpal/docx-js-editor` | `@eigenpal/docx-editor-react` |
| `@eigenpal/docx-js-editor/core` | `@eigenpal/docx-editor-core` |
| `@eigenpal/docx-js-editor/mcp` | `@eigenpal/docx-editor-agents/mcp` |
| `@eigenpal/docx-js-editor/i18n/<code>.json` | `@eigenpal/docx-editor-i18n/<code>` (subpath) or named export off the root |
| `@eigenpal/docx-editor-agents` (AGPL-3.0) | `@eigenpal/docx-editor-agents` (Apache 2.0) |

Install the package set you actually use:

```bash
# Bare minimum for a React editor:
npm uninstall @eigenpal/docx-js-editor
npm install @eigenpal/docx-editor-react

# Vue 3 instead:
npm install @eigenpal/docx-editor-vue

# Add the agent toolkit (also where the agent UI components live now):
npm install @eigenpal/docx-editor-agents

# Standalone i18n (transitively installed by -react and -vue):
npm install @eigenpal/docx-editor-i18n
```

`-core` and `-i18n` are pulled in transitively by `-react` and `-vue`. Install them explicitly only when you import directly from those packages.

## Moved symbols

Five categories of symbols moved across packages (not just subpaths). A plain package-name swap to `@eigenpal/docx-editor-react` won't resolve these. **If a symbol from this list lives in your code, point its import at the new home below, otherwise you'll get a wall of "no exported member" errors.**

| Symbol(s) | Was (0.x) | Now (1.x, recommended) |
|---|---|---|
| `createEmptyDocument`, `createDocumentWithText`, `CreateEmptyDocumentOptions` | `@eigenpal/docx-js-editor` | `@eigenpal/docx-editor-react` or `@eigenpal/docx-editor-vue` (re-exported in 1.0.1 from `-core`) |
| Document-tree types most apps reach for: `Document`, `Comment`, `Paragraph`, `Run`, `Insertion`, `Deletion`, `TrackedChangeInfo`, `Hyperlink`, `Table` | `@eigenpal/docx-js-editor` | `@eigenpal/docx-editor-core` (root entry surfaces them in 1.0.1) |
| Rarer document-tree types: `Image`, `Footnote`, `Endnote`, `TableRow`, `TableCell` | `@eigenpal/docx-js-editor` | `@eigenpal/docx-editor-core/headless` |
| Agent UI components: `AgentPanel`, `AgentChatLog`, `AgentComposer`, `AgentSuggestionChip`, `AgentTimeline` (and their `*Props` types) | `@eigenpal/docx-js-editor` | `@eigenpal/docx-editor-agents/react` (or `/vue`) |
| `PluginHost`, `PluginHostProps`, `PluginHostRef`, `templatePlugin` | `@eigenpal/docx-js-editor` | `@eigenpal/docx-editor-react/plugin-api` |

**Why these moved.** Agent UI primitives ship with the toolkit they pair with, not with the editor. Plugin types live next to the plugin contract. Document types and `createEmptyDocument` are declared in `-core` (framework-agnostic); 1.0.1 re-exports `createEmptyDocument`/`createDocumentWithText` from `-react` and `-vue` so most apps don't need a separate `-core` install, and surfaces the common document-tree types at the `-core` root entry so the deep `-core/headless` subpath only matters for the long tail.

**Pin to ≥1.0.1.** Earlier 1.0.0 required importing `createEmptyDocument` from `@eigenpal/docx-editor-core` (a separate install) and document types from `@eigenpal/docx-editor-core/headless` (an unguessable subpath). 1.0.1 fixed both. If you're on 1.0.0, upgrade the patch version before migrating; it removes most of the import-pain in this guide.

You don't need a script for this. TypeScript will point you at each one: a moved symbol that's still importing from the old package shows up as a `Module has no exported member` error, and the table above gives its new home. Fix them as they come up.

## Remaining imports

Once the moved symbols are handled, every remaining `@eigenpal/docx-js-editor` import changes to `@eigenpal/docx-editor-react`. Only the package name changes; the imported names stay the same.

A few 0.x subpaths don't live under `-react` and need a different package:

| 0.x subpath | 1.x home |
|---|---|
| `@eigenpal/docx-js-editor/core` | `@eigenpal/docx-editor-core` |
| `@eigenpal/docx-js-editor/mcp` | `@eigenpal/docx-editor-agents/mcp` |
| `@eigenpal/docx-js-editor/i18n/<code>.json` | `@eigenpal/docx-editor-i18n` (see [i18n restructure](#i18n-restructure) below) |

## API renames

### `FormattingBar` → `Toolbar`

What was previously called the "formatting bar" is now `Toolbar`, a closer name to what it actually is.

```diff
- import { FormattingBar } from "@eigenpal/docx-js-editor";
+ import { Toolbar } from "@eigenpal/docx-editor-react/ui";
```

### `Toolbar` (composite) → `EditorToolbar`

The old `Toolbar` that combined a menu bar + the formatting buttons is now `EditorToolbar`. The formatting strip on its own is `Toolbar`. The lower-level pieces (`ToolbarButton`, `ToolbarGroup`, `ToolbarSeparator`, `ResponsiveToolbar`) are exported alongside.

```diff
- import { Toolbar } from "@eigenpal/docx-js-editor";
+ import { EditorToolbar } from "@eigenpal/docx-editor-react/ui";
// or compose your own:
+ import { Toolbar, ToolbarButton, ToolbarGroup } from "@eigenpal/docx-editor-react/ui";
```

If you want the same behavior as 0.x's `Toolbar`, use `EditorToolbar`. If you want only the formatting buttons (what 0.x called `FormattingBar`), use the new `Toolbar`.

`MenuBar` from 0.x is gone in 1.x. Compose your own from `ToolbarButton` and `ToolbarGroup`, or use `EditorToolbar` which includes a menu strip by default.

## Removed APIs

### `showPrintButton`

Removed from `<DocxEditor>` and the toolbar. Render your own button if you need it.

```diff
- <DocxEditor documentBuffer={buf} showPrintButton />
+ <DocxEditor documentBuffer={buf} />
```

## i18n restructure

The package changed name (`-i18n` is now standalone) and gained two import styles. Both are supported in **1.0.1+**.

### Locales: subpath or named export

The 1.0 release shipped named exports only and broke per-locale code splitting in the process. 1.0.1 restored subpath exports, so you can pick:

```ts
// Subpath, bundlers tree-shake to just this locale's strings. Best for dynamic loading.
import pl from "@eigenpal/docx-editor-i18n/pl";

// Named, drops the dash for camelCase. Best for static "load all known locales" lists.
import { pl, ptBR } from "@eigenpal/docx-editor-i18n";
```

The diff from 0.x:

```diff
- import pl from "@eigenpal/docx-js-editor/i18n/pl.json";
+ import pl from "@eigenpal/docx-editor-i18n/pl";
```

### Locale codes

| Locale | 0.x JSON path | 1.x subpath | 1.x named export |
|---|---|---|---|
| English | `/i18n/en.json` | `/en` | `en` |
| Polish | `/i18n/pl.json` | `/pl` | `pl` |
| German | `/i18n/de.json` | `/de` | `de` |
| Brazilian Portuguese | `/i18n/pt-BR.json` | `/pt-BR` | `ptBR` |
| Hebrew | `/i18n/he.json` | `/he` | `he` |
| Turkish | `/i18n/tr.json` | `/tr` | `tr` |
| Chinese (Simplified) | `/i18n/zh-CN.json` | `/zh-CN` | `zhCN` |

### Dynamic locale imports

Path-templated dynamic imports work the same shape as before, just against the new package:

```diff
- import(`@eigenpal/docx-js-editor/i18n/${locale}.json`).then(setI18n);
+ import(`@eigenpal/docx-editor-i18n/${locale}`).then((m) => setI18n(m.default));
```

Each subpath emits its own chunk, so the bundler ships only the locale that loaded.

### TypeScript types

In 0.x each locale's type was the inferred `typeof <json>`, concrete and indistinguishable from one another. In 1.x, only `en` is the source-of-truth `LocaleStrings`; the others are `PartialLocaleStrings` (some keys may be missing). Update your local type unions:

```diff
- type LocaleI18n = typeof pl | typeof de | undefined;
+ import type { LocaleStrings, PartialLocaleStrings } from "@eigenpal/docx-editor-i18n";
+ type LocaleI18n = LocaleStrings | PartialLocaleStrings | undefined;
```

## License change

The 0.x line of `@eigenpal/docx-editor-agents` was AGPL-3.0. In 1.0, all five packages are **Apache 2.0**. If you tracked license obligations for compliance review, update the entry. Apache 2.0 is permissive: no copyleft on derivative works.

The non-agents packages (`-core`, `-react`, `-vue`, `-i18n`) were also previously AGPL through `@eigenpal/docx-js-editor`; they're now Apache 2.0 as well.

## Vue users

Vue 3 is a published adapter in 1.0; it didn't exist in 0.x. If you were embedding the editor in a Vue app via the React adapter + a wrapper, drop the wrapper and use `@eigenpal/docx-editor-vue` directly. The surface mirrors React (same component name, hooks-as-composables, same plugin contract). Cross-adapter parity is enforced by `etc/parity.contract.json` upstream. See the [Vue package page](/docs/1.x/vue).

## Verifying the migration

1. **TypeScript first.** TypeScript will flag every moved symbol with a `Module has no exported member` error. Those are your roadmap to the [Moved symbols](#moved-symbols) table.
2. **Build the project.** `next build` / `vite build` catches dynamic-import path errors that TS misses.
3. **Run your test suite.** The behavior of every preserved API is unchanged; tests are the safety net for the import changes.
4. **Check the editor visually** for the missing print button and any toolbar configuration you used to pass via `showPrintButton`.

If something behaves differently and isn't covered above, it's likely a bug rather than an intended change, please file an issue in the [docx-editor repo](https://github.com/eigenpal/docx-editor/issues).

## Where to go next

- [Installation](/docs/1.x/installation), framework-specific setup for 1.x
- [Package overview](/docs/1.x), which package does what
- [API reference](/docs/1.x/api), every export, generated from upstream types
- [0.x archive](/docs/0.x), your old docs are still here if you need them

---

# CorePlugin & Headless API

Source: https://www.docx-editor.dev/docs/1.x/plugins/core-plugins

## What is the Headless API?

The package has two entry points:

```
src/index.ts      → Browser editor (React, needs DOM)
src/headless.ts   → Headless API (Node.js, no DOM needed)
```

The headless API gives you `DocumentAgent`, parsers, serializers, and template processing, everything you need to manipulate DOCX files programmatically in Node.js. No browser, no React, no ProseMirror.

```ts
import { DocumentAgent, parseDocx, processTemplate } from '@eigenpal/docx-editor-react/headless';
```

**CorePlugins** extend the headless API with custom command handlers. They're the server-side equivalent of EditorPlugins.

## When to Use the Headless API

- **API routes**, fill templates, generate documents server-side
- **CI/CD pipelines**, validate templates, extract variables
- **Node.js scripts**, batch-process DOCX files
- **Server-side agents**, programmatic document manipulation

If you need UI panels, overlays, or ProseMirror decorations, use an [EditorPlugin](/docs/1.x/plugins/editor-plugins) instead.

## DocumentAgent

`DocumentAgent` is the main entry point for headless document manipulation:

```ts
import { DocumentAgent } from '@eigenpal/docx-editor-react/headless';
import fs from 'fs';

// Load a DOCX file
const buffer = fs.readFileSync('template.docx');
const agent = await DocumentAgent.fromBuffer(buffer);

// Read content
console.log('Word count:', agent.getWordCount());
console.log('Variables:', agent.getVariables());

// Edit
const edited = agent
  .insertText({ paragraphIndex: 0, offset: 0 }, 'Hello ')
  .applyStyle(0, 'Heading1');

// Fill template variables
const filled = await edited.applyVariables({
  customer_name: 'Jane Doe',
  date: '2024-02-15',
});

// Export
const output = await filled.toBuffer();
fs.writeFileSync('output.docx', Buffer.from(output));
```

### In a Next.js API Route

```ts
// app/api/fill-template/route.ts
import { processTemplate } from '@eigenpal/docx-editor-react/headless';

export async function POST(req: Request) {
  const formData = await req.formData();
  const file = formData.get('file') as File;
  const variables = JSON.parse(formData.get('variables') as string);

  const buffer = await file.arrayBuffer();
  const filled = await processTemplate(buffer, variables);

  return new Response(filled, {
    headers: {
      'Content-Type': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
    },
  });
}
```

### Template Processing Utilities

```ts
import {
  processTemplate,
  getTemplateTags,
  validateTemplate,
} from '@eigenpal/docx-editor-react/headless';

// Get all template variables from a DOCX
const tags = await getTemplateTags(buffer);
// → ['name', 'date', 'items', 'total']

// Validate template syntax
const result = await validateTemplate(buffer);
// → { valid: true } or { valid: false, errors: [...] }

// Fill template with data
const filled = await processTemplate(buffer, {
  name: 'Jane Doe',
  date: '2024-02-15',
  items: [{ name: 'Widget', price: 9.99 }],
  total: '$9.99',
});
```

## CorePlugin Interface

CorePlugins extend `DocumentAgent` with custom command handlers:

```ts
interface CorePlugin {
  id: string;
  name: string;
  version?: string;
  description?: string;
  commandHandlers?: Record<string, CommandHandler>;
  initialize?: () => void | Promise<void>;
  destroy?: () => void | Promise<void>;
  dependencies?: string[];
}
```

### Fields

| Field             | Required | Description                                  |
| ----------------- | -------- | -------------------------------------------- |
| `id`              | Yes      | Unique identifier                            |
| `name`            | Yes      | Human-readable name                          |
| `version`         | No       | Semver version string                        |
| `description`     | No       | Short description                            |
| `commandHandlers` | No       | Map of command type → handler function       |
| `initialize`      | No       | Called once during registration              |
| `destroy`         | No       | Cleanup on unregistration                    |
| `dependencies`    | No       | IDs of plugins that must be registered first |

## Command Handlers

A command handler is a pure function that receives a `Document` and a command, then returns a new `Document`:

```ts
type CommandHandler = (doc: Document, command: PluginCommand) => Document;

interface PluginCommand {
  type: string;
  id?: string;
  position?: Position;
  range?: Range;
  [key: string]: unknown;
}
```

Example, a plugin that adds watermark text:

```ts
import type { CorePlugin, PluginCommand } from '@eigenpal/docx-editor-react';
import type { Document } from '@eigenpal/docx-editor-core';

const watermarkPlugin: CorePlugin = {
  id: 'watermark',
  name: 'Watermark',
  commandHandlers: {
    addWatermark(doc: Document, cmd: PluginCommand) {
      const text = (cmd as { text: string }).text;
      // .., transform doc to add watermark header
      return doc;
    },
  },
};
```

Use it:

```ts
import { pluginRegistry } from '@eigenpal/docx-editor-react';

pluginRegistry.register(watermarkPlugin);

const handler = pluginRegistry.getCommandHandler('addWatermark');
if (handler) {
  const newDoc = handler(doc, { type: 'addWatermark', text: 'DRAFT' });
}
```

## PluginRegistry

The global `pluginRegistry` manages all CorePlugins:

```ts
import { pluginRegistry } from '@eigenpal/docx-editor-react';

// Register
pluginRegistry.register(myPlugin);

// Query
pluginRegistry.has('watermark'); // true
pluginRegistry.getAll(); // CorePlugin[]
pluginRegistry.getCommandTypes(); // ['addWatermark']

// Unregister
pluginRegistry.unregister('watermark');

// Batch registration
import { registerPlugins } from '@eigenpal/docx-editor-react';
registerPlugins([pluginA, pluginB]);
```

## Reference Implementation: Docxtemplater Plugin

The built-in `docxtemplaterPlugin` in `src/core-plugins/docxtemplater/` is a full reference:

- **Command handlers**: `insertTemplateVariable`, `replaceWithTemplateVariable`
- Lazy dependency validation. `processTemplate` checks for `docxtemplater`/`pizzip` at call time

```ts
import { pluginRegistry, docxtemplaterPlugin } from '@eigenpal/docx-editor-react';

pluginRegistry.register(docxtemplaterPlugin);

// Now DocumentAgent can dispatch insertTemplateVariable commands
```

Note: there is also a separate **EditorPlugin** for template UI (`src/plugins/template/`) that handles syntax highlighting and the annotation panel in the browser. The two systems are independent but complement each other, a single feature can span both.

## Next Steps

- [EditorPlugin API](/docs/1.x/plugins/editor-plugins), browser-side UI plugins
- [Examples & Cookbook](/docs/1.x/plugins/examples), advanced patterns
- [Getting Started](/docs/1.x/plugins/getting-started), overview and hello world

---

# EditorPlugin API

Source: https://www.docx-editor.dev/docs/1.x/plugins/editor-plugins

EditorPlugins run in the browser alongside `DocxEditor`. They can contribute UI panels, document overlays, ProseMirror plugins, and scoped CSS.

## How It Works

`PluginHost` wraps `DocxEditor` and manages the plugin lifecycle:

<PluginHostDiagram />

Internally, `PluginHost` uses `React.cloneElement` to inject props into the child `DocxEditor`. This means `DocxEditor` **must** be the direct child of `PluginHost`.

## Quick Start

```tsx
import { DocxEditor, PluginHost, templatePlugin } from '@eigenpal/docx-editor-react';

function Editor({ file }: { file: ArrayBuffer }) {
  return (
    <PluginHost plugins={[templatePlugin]}>
      <DocxEditor documentBuffer={file} />
    </PluginHost>
  );
}
```

## EditorPlugin\<TState\>

```ts
interface EditorPlugin<TState = any> {
  id: string;
  name: string;
  proseMirrorPlugins?: ProseMirrorPlugin[];
  Panel?: React.ComponentType<PluginPanelProps<TState>>;
  panelConfig?: PanelConfig;
  onStateChange?: (view: EditorView) => TState | undefined;
  initialize?: (view: EditorView | null) => TState;
  destroy?: () => void;
  styles?: string;
  renderOverlay?: (
    context: RenderedDomContext,
    state: TState,
    editorView: EditorView | null
  ) => ReactNode;
}
```

### Fields

| Field                | Required | Description                                                                                                               |
| -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `id`                 | Yes      | Unique identifier. Used as key for state storage and CSS `<style>` tag IDs.                                               |
| `name`               | Yes      | Display name shown in panel collapse buttons.                                                                             |
| `proseMirrorPlugins` | No       | ProseMirror plugins merged into the editor. Use for decorations, keymaps, transaction listeners.                          |
| `Panel`              | No       | React component rendered in a side/bottom panel.                                                                          |
| `panelConfig`        | No       | Panel position, size, and collapse behavior.                                                                              |
| `onStateChange`      | No       | Called on every editor state change (input, click, focus, dispatch). Return new `TState` or `undefined` to keep existing. |
| `initialize`         | No       | Called once when the plugin loads. `view` may be `null` if editor hasn't mounted yet. Returns initial `TState`.           |
| `destroy`            | No       | Cleanup callback for timers, subscriptions, DOM listeners.                                                                |
| `styles`             | No       | CSS string injected into `<head>` on mount, removed on unmount.                                                           |
| `renderOverlay`      | No       | Return React elements positioned absolutely over the document pages.                                                      |

## Lifecycle

<PluginLifecycleDiagram />

**Important**: `onStateChange` fires on ANY change, there is no way to subscribe to specific events like "selection changed" or "focus." If you need fine-grained event detection, compare the current `view.state` against your previous state inside `onStateChange`.

## What Plugins Can Do

### 1. Render a Panel

Panel components receive `PluginPanelProps<TState>` with these interaction methods:

```ts
interface PluginPanelProps<TState> {
  editorView: EditorView | null; // Raw ProseMirror view
  doc: ProseMirrorNode | null; // Current document
  scrollToPosition: (pos: number) => void; // Scroll to a PM position
  selectRange: (from: number, to: number) => void; // Select text
  pluginState: TState; // Your managed state
  panelWidth: number; // Current panel width in px
  renderedDomContext: RenderedDomContext | null; // Position mapping (may be null)
}
```

`scrollToPosition` and `selectRange` are convenience methods. For anything beyond these (inserting text, applying formatting, changing selection type), use `editorView` directly:

```ts
function MyPanel({ editorView }: PluginPanelProps<MyState>) {
  const insertText = () => {
    if (!editorView) return;
    const { from } = editorView.state.selection;
    const tr = editorView.state.tr.insertText('Hello', from);
    editorView.dispatch(tr);
  };
  return <button onClick={insertText}>Insert "Hello"</button>;
}
```

This is the intended pattern, the built-in template plugin dispatches transactions directly from its overlay click handlers.

### 2. Render Overlays Over Pages

Overlays are React elements rendered absolutely on top of the visible document pages. Use `RenderedDomContext` to convert ProseMirror positions to pixel coordinates.

```tsx
renderOverlay(context, state, editorView) {
  const coords = context.getCoordinatesForPosition(state.cursorPos);
  if (!coords) return null;

  return (
    <div style={{
      position: 'absolute',
      left: coords.x,
      top: coords.y + coords.height + 4,
      background: '#fff',
      border: '1px solid #ccc',
      padding: 8,
      pointerEvents: 'none',
    }}>
      Tooltip at position {state.cursorPos}
    </div>
  );
}
```

### 3. Add ProseMirror Plugins

For decorations, keymaps, transaction listeners, or custom state:

```ts
import { Plugin, PluginKey } from 'prosemirror-state';
import { DecorationSet } from 'prosemirror-view';

const key = new PluginKey('my-decorations');

const myPlugin: EditorPlugin = {
  id: 'my-decorations',
  name: 'Decorations',
  proseMirrorPlugins: [
    new Plugin({
      key,
      state: {
        init() {
          return DecorationSet.empty;
        },
        apply(tr, set) {
          return set.map(tr.mapping, tr.doc);
        },
      },
      props: {
        decorations(state) {
          return key.getState(state);
        },
      },
    }),
  ],
};
```

Through ProseMirror plugins, you can also add **keyboard shortcuts** and **transaction filters**:

```ts
import { keymap } from 'prosemirror-keymap';

const myPlugin: EditorPlugin = {
  id: 'my-shortcuts',
  name: 'Shortcuts',
  proseMirrorPlugins: [
    keymap({
      'Mod-Shift-w': (state, dispatch) => {
        // Custom shortcut handler
        console.log('Word count shortcut triggered');
        return true;
      },
    }),
  ],
};
```

### 4. Inject Scoped CSS

```ts
const myPlugin: EditorPlugin = {
  id: 'theme',
  name: 'Theme',
  styles: `
    .ep-root .my-highlight {
      background: rgba(59, 130, 246, 0.15);
      border-bottom: 2px solid #3b82f6;
    }
  `,
};
```

Scope selectors under `.ep-root` to avoid conflicts with the host page. Styles are injected as `<style id="plugin-styles-{id}">` and cleaned up on unmount.

### 5. Access the Editor Programmatically (PluginHostRef)

The parent application can interact with plugins via a ref:

```tsx
const hostRef = useRef<PluginHostRef>(null);

// Read/write plugin state from outside
const state = hostRef.current?.getPluginState<WordCountState>('word-count');
hostRef.current?.setPluginState('word-count', { words: 0, characters: 0 });

// Get the ProseMirror EditorView
const view = hostRef.current?.getEditorView();

// Force all plugins to re-derive state
hostRef.current?.refreshPluginStates();

<PluginHost ref={hostRef} plugins={plugins}>
  <DocxEditor documentBuffer={file} />
</PluginHost>;
```

This is how the **host application ties custom functions to the plugin**. For example, a "clear highlights" button in your app's toolbar:

```tsx
function App() {
  const hostRef = useRef<PluginHostRef>(null);

  const clearHighlights = () => {
    hostRef.current?.setPluginState('highlights', { ranges: [] });
  };

  return (
    <>
      <button onClick={clearHighlights}>Clear Highlights</button>
      <PluginHost ref={hostRef} plugins={[highlightPlugin]}>
        <DocxEditor documentBuffer={file} />
      </PluginHost>
    </>
  );
}
```

## PanelConfig

```ts
interface PanelConfig {
  position: 'left' | 'right' | 'bottom'; // default: 'right'
  defaultSize: number; // pixels, default: 280
  minSize?: number; // default: 200
  maxSize?: number; // default: 500
  resizable?: boolean; // default: true
  collapsible?: boolean; // default: true
  defaultCollapsed?: boolean; // default: false
}
```

- **Right** panels render inside the editor viewport and scroll with the document.
- **Left** and **bottom** panels render outside the viewport as fixed sidebars.

## RenderedDomContext

The editor uses a dual-DOM architecture: a hidden ProseMirror instance handles editing, while LayoutPainter draws the paginated visual output. `RenderedDomContext` translates between the two.

```ts
interface RenderedDomContext {
  pagesContainer: HTMLElement;
  zoom: number;
  getCoordinatesForPosition(pmPos: number): PositionCoordinates | null;
  findElementsForRange(from: number, to: number): Element[];
  getRectsForRange(
    from: number,
    to: number
  ): Array<{ x: number; y: number; width: number; height: number }>;
  getContainerOffset(): { x: number; y: number };
}

interface PositionCoordinates {
  x: number;
  y: number;
  height: number;
}
```

Both types are exported from the main package:

```ts
import type { RenderedDomContext, PositionCoordinates } from '@eigenpal/docx-editor-react';
```

**Important**: `renderedDomContext` may be `null` during initial render (before LayoutPainter has painted pages). Always null-check before using.

## What Plugins Cannot Do

These are explicit limitations of the current API:

| Capability                                            | Status        | Workaround                                                          |
| ----------------------------------------------------- | ------------- | ------------------------------------------------------------------- |
| Add toolbar buttons                                   | Not supported | Render buttons in your Panel component                              |
| Add context menu items                                | Not supported | Use overlay + mousedown listener for custom menus                   |
| Subscribe to specific events (selection, focus, blur) | Not supported | Compare state inside `onStateChange`                                |
| Communicate between plugins                           | Not supported | Coordinate through the parent app via `PluginHostRef`               |
| Hook into save/load                                   | Not supported | Parent app handles save; plugins read state from `editorView`       |
| Persist custom data in the DOCX file                  | Not supported | Store plugin data externally                                        |
| Intercept transactions before they apply              | Partial       | Use ProseMirror plugin's `filterTransaction` or `appendTransaction` |

For transaction interception, use a ProseMirror plugin:

```ts
proseMirrorPlugins: [
  new Plugin({
    filterTransaction(tr) {
      // Return false to block a transaction
      return true;
    },
    appendTransaction(transactions, oldState, newState) {
      // Return a new transaction to apply after the original
      return null;
    },
  }),
],
```

## Best Practices

- **Memoize `onStateChange`**: if you return a new object every call, the panel re-renders on every keystroke. Compare values before returning a new object.
- **Prevent focus stealing**: ProseMirror captures `mousedown`. Dropdowns and dialogs in panels need `onMouseDown` with `event.stopPropagation()`.
- **Scope CSS under `.ep-root`**: use inline styles on overlay/panel elements to avoid Tailwind collisions.
- **`renderOverlay` must be fast**: it runs on every state change. Avoid heavy DOM queries inside it.
- **Null-check `renderedDomContext`**: it's `null` until layout-painter finishes the first render.
- **Null-check `editorView`**: it's `null` until ProseMirror mounts. Don't assume it's always available.

## Full Example: Template Plugin

The built-in template plugin (`src/plugins/template/`) demonstrates every feature:

- **ProseMirror plugin** scans the doc for `{variable}` patterns, builds a `DecorationSet`
- **Panel** lists all detected tags with click-to-navigate
- **Overlay** renders colored highlights over the visible pages with hover/click handlers
- **CSS** styles the decorations and hover states
- **State** tracks tags, hovered ID, and selected ID

Key pattern from the template plugin, dispatching transactions from an overlay:

```ts
renderOverlay: (context, state, editorView) => {
  return <TemplateHighlightOverlay
    tags={state.tags}
    onSelect={(tagId) => {
      if (!editorView) return;
      const tag = state.tags.find(t => t.id === tagId);
      if (!tag) return;
      const tr = editorView.state.tr.setSelection(
        TextSelection.near(editorView.state.doc.resolve(tag.from))
      );
      editorView.dispatch(tr);
    }}
  />;
}
```

## Internal Extension System

The editor's core formatting (bold, italic, tables, etc.) uses a separate internal extension system in `src/prosemirror/extensions/`. This is **not** part of the plugin API, use `EditorPlugin` for all external extensions. See [docs/EXTENSIONS.md](https://github.com/eigenpal/docx-editor/blob/main/docs/EXTENSIONS.md) for details.

---

# Plugin Examples & Cookbook

Source: https://www.docx-editor.dev/docs/1.x/plugins/examples

## Example Plugins

### Hello World. Word Count

A minimal `EditorPlugin` with a right-hand panel showing word, character, and paragraph counts. Demonstrates `initialize`, `onStateChange`, `Panel`, and `panelConfig`.

```bash
cd examples/plugins/hello-world
npm install && npm run dev    # http://localhost:5175
```

Source: [`examples/plugins/hello-world/src/wordCountPlugin.ts`](https://github.com/eigenpal/docx-editor/tree/main/examples/plugins/hello-world/src/wordCountPlugin.ts)

### Docxtemplater

Full-featured template variable plugin combining both plugin systems:

- **EditorPlugin** (`src/plugins/template/`). ProseMirror decorations that highlight `{variable}` tags, plus an annotation panel listing the template schema
- **CorePlugin** (`src/core-plugins/docxtemplater/`), headless command handlers for server-side template operations

```bash
cd examples/plugins/docxtemplater
npm install && npm run dev    # http://localhost:5174
```

Source: [`examples/plugins/docxtemplater/`](https://github.com/eigenpal/docx-editor/tree/main/examples/plugins/docxtemplater/)

## Patterns

### Combining EditorPlugin + CorePlugin

A single feature can span both systems. The docxtemplater plugin does this:

| Concern                 | System                                 | Location                          |
| ----------------------- | -------------------------------------- | --------------------------------- |
| Syntax highlighting     | EditorPlugin (ProseMirror decorations) | `src/plugins/template/`           |
| Annotation panel        | EditorPlugin (Panel component)         | `src/plugins/template/`           |
| Insert variable command | CorePlugin (command handler)           | `src/core-plugins/docxtemplater/` |

Register both independently, they share data through the `Document` model.

### Adding Keyboard Shortcuts

Use `proseMirrorPlugins` with `prosemirror-keymap`:

```ts
import { keymap } from 'prosemirror-keymap';

const shortcutPlugin: EditorPlugin = {
  id: 'my-shortcuts',
  name: 'Shortcuts',
  proseMirrorPlugins: [
    keymap({
      'Mod-Shift-c': (state, dispatch) => {
        const text = state.doc.textContent;
        const words = text.split(/\s+/).filter(Boolean).length;
        console.log(`Word count: ${words}`);
        return true; // handled
      },
    }),
  ],
};
```

### Filtering or Appending Transactions

Use ProseMirror plugin hooks for transaction middleware:

```ts
import { Plugin } from 'prosemirror-state';

const guardPlugin: EditorPlugin = {
  id: 'max-length',
  name: 'Max Length',
  proseMirrorPlugins: [
    new Plugin({
      filterTransaction(tr, state) {
        // Block transactions that would exceed 10000 characters
        if (tr.docChanged) {
          const newSize = tr.doc.textContent.length;
          if (newSize > 10000) return false;
        }
        return true;
      },
    }),
  ],
};
```

### ProseMirror Decorations

```ts
import { Plugin, PluginKey } from 'prosemirror-state';
import { Decoration, DecorationSet } from 'prosemirror-view';

const key = new PluginKey('spell-check');

const spellCheckPlugin: EditorPlugin = {
  id: 'spell-check',
  name: 'Spell Check',
  proseMirrorPlugins: [
    new Plugin({
      key,
      state: {
        init(_, state) {
          return findErrors(state.doc);
        },
        apply(tr, decorations, oldState, newState) {
          if (tr.docChanged) return findErrors(newState.doc);
          return decorations.map(tr.mapping, tr.doc);
        },
      },
      props: {
        decorations(state) {
          return key.getState(state);
        },
      },
    }),
  ],
};

function findErrors(doc: ProseMirrorNode): DecorationSet {
  const decorations: Decoration[] = [];
  // .., walk doc, create Decoration.inline(from, to, { class: 'error' })
  return DecorationSet.create(doc, decorations);
}
```

### Overlays with Position Mapping

Render absolutely-positioned React elements over the visible pages:

```tsx
renderOverlay(context, state, editorView) {
  if (!editorView) return null;
  const { from } = editorView.state.selection;
  const coords = context.getCoordinatesForPosition(from);
  if (!coords) return null;

  return (
    <div style={{
      position: 'absolute',
      left: coords.x,
      top: coords.y + coords.height + 4,
      background: '#fff',
      border: '1px solid #ccc',
      borderRadius: 4,
      padding: 8,
      pointerEvents: 'none',
    }}>
      Cursor at position {from}
    </div>
  );
}
```

### Connecting Plugin to Host App UI

Use `PluginHostRef` to bridge your app's buttons/controls with plugin state:

```tsx
function App() {
  const hostRef = useRef<PluginHostRef>(null);

  const clearHighlights = () => {
    hostRef.current?.setPluginState('highlights', { ranges: [] });
  };

  const getWordCount = () => {
    const state = hostRef.current?.getPluginState<{ words: number }>('word-count');
    alert(`${state?.words ?? 0} words`);
  };

  const insertAtCursor = () => {
    const view = hostRef.current?.getEditorView();
    if (!view) return;
    const { from } = view.state.selection;
    view.dispatch(view.state.tr.insertText('Inserted by app', from));
  };

  return (
    <>
      <div className="my-app-toolbar">
        <button onClick={clearHighlights}>Clear</button>
        <button onClick={getWordCount}>Count</button>
        <button onClick={insertAtCursor}>Insert</button>
      </div>
      <PluginHost ref={hostRef} plugins={[wordCountPlugin, highlightPlugin]}>
        <DocxEditor documentBuffer={file} />
      </PluginHost>
    </>
  );
}
```

## API Cookbook

### Scroll to a ProseMirror Position

From a panel component:

```ts
function MyPanel({ scrollToPosition }: PluginPanelProps<MyState>) {
  return <button onClick={() => scrollToPosition(42)}>Go to pos 42</button>;
}
```

### Select a Text Range

```ts
function MyPanel({ selectRange }: PluginPanelProps<MyState>) {
  return <button onClick={() => selectRange(10, 25)}>Select range</button>;
}
```

### Read Document Text

```ts
onStateChange(view) {
  const text = view.state.doc.textContent;
  const nodeCount = view.state.doc.childCount;
  return { text, nodeCount };
}
```

### Dispatch a ProseMirror Transaction

From a panel (or overlay) that has `editorView`:

```ts
function MyPanel({ editorView }: PluginPanelProps<MyState>) {
  const makeBold = () => {
    if (!editorView) return;
    const { from, to } = editorView.state.selection;
    if (from === to) return;
    // Look up the bold mark type from the schema
    const boldType = editorView.state.schema.marks.bold;
    if (!boldType) return;
    editorView.dispatch(
      editorView.state.tr.addMark(from, to, boldType.create())
    );
  };
  return <button onClick={makeBold}>Bold</button>;
}
```

### Get Rects for a Range (Multi-line Highlight)

```ts
renderOverlay(context, state) {
  const rects = context.getRectsForRange(state.from, state.to);
  return (
    <>
      {rects.map((r, i) => (
        <div key={i} style={{
          position: 'absolute',
          left: r.x, top: r.y,
          width: r.width, height: r.height,
          background: 'rgba(255, 200, 0, 0.3)',
          pointerEvents: 'none',
        }} />
      ))}
    </>
  );
}
```

### Detect Selection Changes in onStateChange

Since there's no dedicated selection event, compare states:

```ts
let lastFrom = -1;
let lastTo = -1;

const selectionPlugin: EditorPlugin<SelectionInfo> = {
  id: 'selection-tracker',
  name: 'Selection',
  onStateChange(view) {
    const { from, to } = view.state.selection;
    if (from !== lastFrom || to !== lastTo) {
      lastFrom = from;
      lastTo = to;
      return { from, to, hasSelection: from !== to };
    }
    return undefined; // no change, skip re-render
  },
};
```

---

# Plugin Getting Started

Source: https://www.docx-editor.dev/docs/1.x/plugins/getting-started

The docx-editor has two plugin systems for different use cases:

|              | **EditorPlugin**                                           | **CorePlugin**                                         |
| ------------ | ---------------------------------------------------------- | ------------------------------------------------------ |
| Environment  | Browser (React)                                            | Node.js (headless)                                     |
| Purpose      | UI panels, overlays, ProseMirror decorations               | Command handlers for server-side document manipulation |
| Registration | `<PluginHost plugins={[...]}>` wrapping `<DocxEditor>`     | `pluginRegistry.register(plugin)`                      |
| State model  | Reactive. `onStateChange` fires on every edit/click/focus | Stateless, pure functions transforming `Document`     |
| Entry point  | `src/plugin-api`                                           | `src/core-plugins`                                     |

Most plugins are **EditorPlugins**. Use a **CorePlugin** when you need headless document manipulation. API routes, Node.js scripts, CI pipelines, without a browser.

**Important**: these two systems run in completely different environments. EditorPlugins run in your React app in the browser. CorePlugins run in Node.js (API routes, scripts, etc.). They share the same `Document` model and parsers, but they don't communicate with each other. See [CorePlugin & Headless API](/docs/1.x/plugins/core-plugins) for the full architecture.

## How Registration Works

### EditorPlugin

Plugins are passed as an array to `PluginHost`, which wraps your `DocxEditor`:

```tsx
import { DocxEditor, PluginHost } from '@eigenpal/docx-editor-react';
import { myPlugin } from './myPlugin';

<PluginHost plugins={[myPlugin]}>
  <DocxEditor documentBuffer={file} />
</PluginHost>;
```

`PluginHost` uses `React.cloneElement` internally to inject the plugin's ProseMirror plugins and overlay renderers into `DocxEditor`. It also wraps the editor's `dispatch` function to detect state changes and call your `onStateChange` callbacks.

**There is no imperative `register()` call**, the plugin array is declarative. Adding or removing a plugin means changing the array prop.

### CorePlugin

CorePlugins are registered imperatively on the global registry:

```ts
import { pluginRegistry, docxtemplaterPlugin } from '@eigenpal/docx-editor-react';

pluginRegistry.register(docxtemplaterPlugin);
```

## Hello World. Word Count Plugin

### 1. Define plugin state

```ts
interface WordCountState {
  words: number;
  characters: number;
  paragraphs: number;
}
```

### 2. Create the panel component

The panel receives `PluginPanelProps<TState>`. Key props:

- `pluginState`: your managed state
- `editorView`: raw ProseMirror `EditorView` (use for dispatching transactions)
- `scrollToPosition(pos)`: scroll to a position
- `selectRange(from, to)`: select a text range
- `renderedDomContext`: map PM positions to pixel coordinates (may be null)

```tsx
function WordCountPanel({ pluginState }: PluginPanelProps<WordCountState>) {
  return (
    <div style={{ padding: 16 }}>
      <p>Words: {pluginState.words}</p>
      <p>Characters: {pluginState.characters}</p>
      <p>Paragraphs: {pluginState.paragraphs}</p>
    </div>
  );
}
```

### 3. Wire it into an EditorPlugin

```ts
import type { EditorPlugin } from '@eigenpal/docx-editor-react';

export const wordCountPlugin: EditorPlugin<WordCountState> = {
  id: 'word-count',
  name: 'Word Count',
  Panel: WordCountPanel,
  panelConfig: { position: 'right', defaultSize: 220, collapsible: true },

  initialize: () => ({ words: 0, characters: 0, paragraphs: 0 }),

  onStateChange(view) {
    const text = view.state.doc.textContent;
    return {
      words: text.split(/\s+/).filter(Boolean).length,
      characters: text.length,
      paragraphs: view.state.doc.childCount,
    };
  },
};
```

### 4. Mount it

```tsx
<PluginHost plugins={[wordCountPlugin]}>
  <DocxEditor documentBuffer={file} />
</PluginHost>
```

### 5. Connect it to your app

The parent app can interact with plugin state via `PluginHostRef`:

```tsx
const hostRef = useRef<PluginHostRef>(null);

// Read plugin state from the outside
const count = hostRef.current?.getPluginState<WordCountState>('word-count');
console.log(`Document has ${count?.words} words`);

// Force all plugins to refresh
hostRef.current?.refreshPluginStates();

<PluginHost ref={hostRef} plugins={[wordCountPlugin]}>
  <DocxEditor documentBuffer={file} />
</PluginHost>;
```

### 6. Run the example

```bash
cd examples/plugins/hello-world
npm install   # or bun install
npm run dev   # opens http://localhost:5175
```

## What Plugins Can and Cannot Do

**Can do:**

- Render panels (left/right/bottom) with full React UI
- Render overlays positioned over the document pages
- Add ProseMirror plugins (decorations, keymaps, transaction filters)
- Inject/remove scoped CSS
- Read the full ProseMirror state (`editorView.state`)
- Dispatch ProseMirror transactions (`editorView.dispatch(tr)`)
- Scroll to positions and select text ranges

**Cannot do (current limitations):**

- Add buttons to the built-in toolbar
- Add items to the context menu
- Subscribe to specific events (only `onStateChange` for all changes)
- Communicate directly between plugins
- Hook into save/load
- Persist custom data in the DOCX file

See [EditorPlugin API](/docs/1.x/plugins/editor-plugins) for the full reference including workarounds.

## Next Steps

- [EditorPlugin API reference](/docs/1.x/plugins/editor-plugins), full interface, lifecycle, panels, overlays, limitations
- [CorePlugin & Headless API](/docs/1.x/plugins/core-plugins), server-side document manipulation, command handlers
- [Examples & Cookbook](/docs/1.x/plugins/examples), advanced patterns and recipes

---

# 1.x/plugins/index

Source: https://www.docx-editor.dev/docs/1.x/plugins/index

The plugin documentation has moved to [`docs/plugins/`](/docs/1.x/plugins).

- [Getting Started](/docs/1.x/plugins/getting-started), overview, decision table, hello world walkthrough
- [EditorPlugin API](/docs/1.x/plugins/editor-plugins), browser-side UI plugins (panels, overlays, ProseMirror)
- [CorePlugin & Headless API](/docs/1.x/plugins/core-plugins), server-side document manipulation, command handlers
- [Examples & Cookbook](/docs/1.x/plugins/examples), advanced patterns and API recipes

---

# React Examples

Source: https://www.docx-editor.dev/docs/1.x/react/examples

Each example is a self-contained component. Drop into a React file, swap the data source, render.

## Load a document from a URL

```tsx
import { useEffect, useState } from "react";
import { DocxEditor } from "@eigenpal/docx-editor-react";
import "@eigenpal/docx-editor-react/styles.css";

export function Editor({ url }: { url: string }) {
  const [buf, setBuf] = useState<ArrayBuffer | null>(null);

  useEffect(() => {
    let cancelled = false;
    fetch(url)
      .then((r) => r.arrayBuffer())
      .then((b) => {
        if (!cancelled) setBuf(b);
      });
    return () => {
      cancelled = true;
    };
  }, [url]);

  return <DocxEditor documentBuffer={buf} />;
}
```

`null` vs `undefined`: `null` mounts an empty document immediately; `undefined` defers the mount until the buffer arrives (skips the empty-state flash).

## Load from a file input

```tsx
import { useState } from "react";
import { DocxEditor } from "@eigenpal/docx-editor-react";

export function FileEditor() {
  const [buf, setBuf] = useState<ArrayBuffer | null>(null);

  return (
    <>
      <input
        type="file"
        accept=".docx,application/vnd.openxmlformats-officedocument.wordprocessingml.document"
        onChange={async (e) => {
          const file = e.target.files?.[0];
          if (file) setBuf(await file.arrayBuffer());
        }}
      />
      {buf && <DocxEditor documentBuffer={buf} />}
    </>
  );
}
```

## Autosave on change

Debounce `onChange`, persist the serialized buffer.

```tsx
import { useRef, useCallback } from "react";
import { DocxEditor, type DocxEditorRef } from "@eigenpal/docx-editor-react";

function useDebouncedFn<T extends (...args: unknown[]) => void>(fn: T, ms: number) {
  const timer = useRef<number | null>(null);
  return useCallback(
    (...args: Parameters<T>) => {
      if (timer.current) window.clearTimeout(timer.current);
      timer.current = window.setTimeout(() => fn(...args), ms);
    },
    [fn, ms],
  );
}

export function AutosaveEditor({ docId }: { docId: string }) {
  const ref = useRef<DocxEditorRef>(null);

  const save = useDebouncedFn(async () => {
    const buf = await ref.current?.save();
    if (!buf) return;
    await fetch(`/api/documents/${docId}`, { method: "PUT", body: buf });
  }, 1500);

  return <DocxEditor ref={ref} documentBuffer={null} onChange={save} />;
}
```

## Controlled comments

Own the comment array; mirror into a backing store.

```tsx
import { useState } from "react";
import { DocxEditor } from "@eigenpal/docx-editor-react";
import type { Comment } from "@eigenpal/docx-editor-core";

export function ReviewEditor({ buf, author }: { buf: ArrayBuffer; author: string }) {
  const [comments, setComments] = useState<Comment[]>([]);

  return (
    <DocxEditor
      documentBuffer={buf}
      author={author}
      comments={comments}
      onCommentsChange={(next) => {
        setComments(next);
        void fetch("/api/comments", {
          method: "PUT",
          body: JSON.stringify(next),
          headers: { "content-type": "application/json" },
        });
      }}
    />
  );
}
```

## Suggesting mode (tracked changes)

```tsx
import { useState } from "react";
import { DocxEditor, type EditorMode } from "@eigenpal/docx-editor-react";

export function ReviewerEditor({ buf, reviewer }: { buf: ArrayBuffer; reviewer: string }) {
  const [mode, setMode] = useState<EditorMode>("suggesting");

  return (
    <DocxEditor
      documentBuffer={buf}
      author={reviewer}
      mode={mode}
      onModeChange={setMode}
    />
  );
}
```

Edits made in `"suggesting"` mode wrap in revision markup. The owner of the document can accept or reject them later, individually or all at once, from the tracked-changes sidebar.

As of 1.1.0 the editor tracks more than inline text edits. Paragraph breaks, paragraph-property changes, table row/cell insert/delete/merge, inserted and deleted images, and list/numbering changes are all recorded as real revisions, shown in the sidebar, and round-tripped to Word's `<w:ins>` / `<w:del>` markup. Accept-all and reject-all resolve every revision type, and rejecting a list change cleanly reverts both the text and the numbering.

## Custom toolbar

Hide the default toolbar, compose your own from the building blocks in `/ui`. `EditorToolbar` is the full composite the default chrome uses; `Toolbar` is the formatting-button strip on its own; `ResponsiveToolbar` adapts to width. Or build from `ToolbarButton`, `ToolbarGroup`, `ToolbarSeparator`.

```tsx
import { DocxEditor } from "@eigenpal/docx-editor-react";
import {
  Toolbar,
  ToolbarButton,
  ToolbarGroup,
  ToolbarSeparator,
} from "@eigenpal/docx-editor-react/ui";

export function CustomChromeEditor({ buf }: { buf: ArrayBuffer }) {
  return (
    <div className="flex flex-col h-full">
      <div className="border-b p-2 flex items-center justify-between">
        <ToolbarGroup>
          <ToolbarButton command="bold" />
          <ToolbarButton command="italic" />
          <ToolbarSeparator />
          <ToolbarButton command="undo" />
        </ToolbarGroup>
        <SaveStatus />
      </div>
      <Toolbar />
      <DocxEditor showToolbar={false} documentBuffer={buf} />
    </div>
  );
}
```

In 0.x the formatting buttons were called `FormattingBar`. They're now `Toolbar`. The old composite is now `EditorToolbar`. See [migration](/docs/1.x/migration#api-renames).

<ToolbarCustomDemo />

## Custom fonts

Register self-hosted font files so the editor renders and measures them, then list the families in the picker. `fonts` injects the `@font-face` rules; `fontFamilies` controls the toolbar dropdown. Added in 1.1.0.

```tsx
import { DocxEditor } from "@eigenpal/docx-editor-react";
import "@eigenpal/docx-editor-react/styles.css";

// Module-level so the array identity is stable across renders.
const FONTS = [
  { family: "Inter", src: "/fonts/Inter-Regular.woff2" },
  { family: "Inter", src: "/fonts/Inter-Bold.woff2", weight: 700 },
  { family: "JetBrains Mono", src: "/fonts/JetBrainsMono-Regular.woff2" },
];

export function BrandedEditor({ buf }: { buf: ArrayBuffer }) {
  return (
    <DocxEditor
      documentBuffer={buf}
      fonts={FONTS}
      fontFamilies={["Inter", "JetBrains Mono", "Arial", "Times New Roman"]}
      onError={(err) => console.error("font or parse error", err)}
    />
  );
}
```

Each `FontDefinition` is `{ family, src, weight? }`. `src` points at a `woff2`/`woff`/`ttf`/`otf` file you serve. The paths above (`/fonts/...`) resolve against your site root, so drop the files in your static directory (`public/` in Next.js or Vite). Register multiple weights of one family as separate entries that share `family`. Match the `family` name to what your documents reference so the right glyphs paint. Font-load failures surface through `onError` (falling back to `console.warn` when no handler is attached).

For hosts that don't use the React or Vue adapter, drive the same registration through `loadFontDefinitions` from `@eigenpal/docx-editor-core/utils`.

## Read-only viewer

```tsx
import { DocxEditor } from "@eigenpal/docx-editor-react";

export function Viewer({ buf }: { buf: ArrayBuffer }) {
  return (
    <DocxEditor
      documentBuffer={buf}
      readOnly
      showToolbar={false}
      showZoomControl={false}
    />
  );
}
```

`readOnly` disables every edit affordance. Pair with `showToolbar={false}` for a viewer-only feel.

<ReadOnlyDemo />

## Realtime collaboration (Yjs)

```tsx
import * as Y from "yjs";
import { WebrtcProvider } from "y-webrtc";
import { ySyncPlugin, yCursorPlugin, yUndoPlugin } from "y-prosemirror";
import { DocxEditor } from "@eigenpal/docx-editor-react";

const ydoc = new Y.Doc();
const provider = new WebrtcProvider("room-1", ydoc);

const yXml = ydoc.getXmlFragment("docx");
const yComments = ydoc.getArray<Comment>("comments");

export function CollabEditor({ buf }: { buf: ArrayBuffer }) {
  return (
    <DocxEditor
      documentBuffer={buf}
      author={localStorage.getItem("name") ?? "Anonymous"}
      externalPlugins={[
        ySyncPlugin(yXml),
        yCursorPlugin(provider.awareness),
        yUndoPlugin(),
      ]}
      comments={yComments.toArray()}
      onCommentsChange={(next) => {
        ydoc.transact(() => {
          yComments.delete(0, yComments.length);
          yComments.push(next);
        });
      }}
    />
  );
}
```

End-to-end walkthrough (provider choices, presence, comment sync) in [Realtime collaboration](/docs/1.x/realtime-collaboration).

## Agent panel

The `agentPanel.render` slot renders a side panel next to the document.

```tsx
import { useRef } from "react";
import { DocxEditor, type DocxEditorRef } from "@eigenpal/docx-editor-react";
import {
  AgentChatLog,
  AgentComposer,
  useDocxAgentTools,
} from "@eigenpal/docx-editor-agents/react";
import { useChat } from "@ai-sdk/react";

export function EditorWithAgent({ buf }: { buf: ArrayBuffer }) {
  const editorRef = useRef<DocxEditorRef>(null);
  const { tools } = useDocxAgentTools({ editorRef });
  const chat = useChat({ api: "/api/agent-chat", body: { tools } });

  return (
    <DocxEditor
      ref={editorRef}
      documentBuffer={buf}
      agentPanel={{
        render: () => (
          <>
            <AgentChatLog messages={chat.messages} />
            <AgentComposer onSubmit={chat.sendMessage} />
          </>
        ),
      }}
    />
  );
}
```

Server-side route + full setup in [Agents → Live editor](/docs/1.x/agents/live-editor).

<AgentChatDemo />

## See also

- [Props reference](/docs/1.x/react/props)
- [React API reference](/docs/1.x/api/react)
- [Realtime collaboration](/docs/1.x/realtime-collaboration)
- [Agents](/docs/1.x/agents)

---

# 1.x/react/index

Source: https://www.docx-editor.dev/docs/1.x/react/index

<PackageStats name="@eigenpal/docx-editor-react" />

## Install

```bash
npm install @eigenpal/docx-editor-react
```

Pulls in `@eigenpal/docx-editor-core` and `@eigenpal/docx-editor-i18n`. Add `@eigenpal/docx-editor-agents` if you need the agent toolkit.

## Quickstart

```tsx
import { DocxEditor } from "@eigenpal/docx-editor-react";
import "@eigenpal/docx-editor-react/styles.css";

export default function App() {
  return <DocxEditor documentBuffer={null} />;
}
```

On Next.js App Router, render this inside a `"use client"` component. ProseMirror touches the DOM at mount, so there's nothing to SSR. The [Next.js DOCX editor guide](/blog/nextjs-docx-editor) walks through file uploads, saving to an API route, and the common errors.

<DemoPlayground />

## Subpaths

- `@eigenpal/docx-editor-react`: `<DocxEditor>`, `DocxEditorRef`, `DocxEditorProps`, `EditorMode`, `createEmptyDocument` (re-exported from `-core` in 1.0.1)
- `@eigenpal/docx-editor-react/ui`: `Toolbar`, `EditorToolbar`, `ResponsiveToolbar`, `TableToolbar`, `ToolbarButton`, `ToolbarGroup`, `ToolbarSeparator`, `ColorPicker`, font/color pickers
- `@eigenpal/docx-editor-react/hooks`: `useHistory`, `useFindReplace`, `useAutoSave`, `useClipboard`, `useTableSelection`, `useWheelZoom`, `useDragAutoScroll`
- `@eigenpal/docx-editor-react/dialogs`: hyperlink, find/replace, paste special, page setup, keyboard shortcuts
- `@eigenpal/docx-editor-react/plugin-api`: `PluginHost`, plugin registration types
- `@eigenpal/docx-editor-react/styles`: CSS

Every export is in the [API reference](/docs/1.x/api/react).

## Loading a document

`documentBuffer` takes an `ArrayBuffer`. Fetch and pass:

```tsx
const [buf, setBuf] = useState<ArrayBuffer | null>(null);

useEffect(() => {
  fetch("/template.docx")
    .then((r) => r.arrayBuffer())
    .then(setBuf);
}, []);

return <DocxEditor documentBuffer={buf} />;
```

`null` mounts an empty document. `undefined` defers mount until the buffer arrives (useful when you want to skip the empty-state flash).

## Ref methods

`DocxEditorRef` exposes imperative methods through `forwardRef`:

```tsx
import { useRef } from "react";
import { DocxEditor, type DocxEditorRef } from "@eigenpal/docx-editor-react";

const ref = useRef<DocxEditorRef>(null);

ref.current?.addComment({ paraId: "ABC12300", text: "Tighten this." });
ref.current?.scrollToParaId("DEF45600");
```

`paraId` is Word's `w14:paraId` attribute. It survives concurrent edits and round-trips through OOXML, which is why we use it instead of positional addressing. Every method signature is in the [API reference](/docs/1.x/api/react).

The ref also reaches block-level content controls in the live document: `getContentControls` lists them (filtered by tag, alias, id, or type), `scrollToContentControl` brings one into view, and `setContentControlContent` / `setContentControlValue` / `removeContentControl` edit one by tag as normal undoable edits. Locked controls are refused unless forced. The Vue adapter pairs the same methods.

## Toolbar

`@eigenpal/docx-editor-react/ui` ships the building blocks. `EditorToolbar` is the full composite the default chrome uses; `Toolbar` is the formatting-button strip on its own; `ResponsiveToolbar` wraps either with adaptive layout. Compose your own from `ToolbarButton`, `ToolbarGroup`, `ToolbarSeparator`:

```tsx
import { DocxEditor } from "@eigenpal/docx-editor-react";
import {
  EditorToolbar,
  Toolbar,
  ToolbarButton,
  ToolbarGroup,
} from "@eigenpal/docx-editor-react/ui";
```

In 0.x the formatting buttons were called `FormattingBar` and the composite was `Toolbar`. We renamed: the formatting buttons are now `Toolbar`, the composite is `EditorToolbar`. See [migration](/docs/1.x/migration) for the rename table.

## Agent integration

Wire AI tools to a live editor with `@eigenpal/docx-editor-agents/react`:

```tsx
import { DocxEditor } from "@eigenpal/docx-editor-react";
import { useDocxAgentTools } from "@eigenpal/docx-editor-agents/react";
```

Full client + server wiring is on [Agents → Live editor](/docs/1.x/agents/live-editor).

## Where to next

- [API reference](/docs/1.x/api/react)
- [Next.js DOCX editor guide](/blog/nextjs-docx-editor)
- [Migration: 0.x → 1.x](/docs/1.x/migration)
- [Plugins](/docs/1.x/plugins)
- [Agents](/docs/1.x/agents)

---

# Props

Source: https://www.docx-editor.dev/docs/1.x/react/props

`<DocxEditor>` is configured through props. Groups below match how you'd reach for them in practice. The full generated reference (every prop, every type signature) is at [/docs/1.x/api/react](/docs/1.x/api/react).

## Document input

How the editor receives the document. Use `documentBuffer` for raw bytes; use `document` when you've already parsed.

| Prop | Type | Description |
|---|---|---|
| `documentBuffer` | `DocxInput \| null` | `ArrayBuffer`, `Uint8Array`, `Blob`, or `File`. Most common entry. `null` mounts an empty document. |
| `document` | `Document \| null` | Pre-parsed `-core` document tree. Skip the parser if you already have one. |

```tsx
// From a fetch
const buf = await fetch("/template.docx").then((r) => r.arrayBuffer());
<DocxEditor documentBuffer={buf} />;

// From a file input
<input type="file" accept=".docx" onChange={(e) => setBuf(e.target.files?.[0] ?? null)} />
<DocxEditor documentBuffer={buf} />

// Empty document (mounts with no content; useful when collecting input from scratch)
<DocxEditor documentBuffer={null} />
```

## Mode and read-only

Editing mode and the suggest/view/read-only states. Pair with `onModeChange` for controlled mode.

| Prop | Type | Default | Description |
|---|---|---|---|
| `mode` | `EditorMode` | `"editing"` | `"editing"` \| `"suggesting"` \| `"viewing"`. For read-only, use the `readOnly` boolean below. |
| `onModeChange` | `(mode) => void` | | Controlled mode handler. Without it, the editor manages mode internally. |
| `readOnly` | `boolean` | `false` | Independent of `mode`. Disables every input affordance (typing, toolbar buttons, dialogs) regardless of which mode is active. |

```tsx
const [mode, setMode] = useState<EditorMode>("editing");

<DocxEditor
  documentBuffer={buf}
  mode={mode}
  onModeChange={setMode}
/>;
```

`"suggesting"` wraps every edit as a tracked change. Use it for review flows.

<ModeToggleDemo />

## Comments and collaboration

Pull author identity in, push comment state back out.

| Prop | Type | Description |
|---|---|---|
| `author` | `string` | Author name attached to new comments and tracked changes. |
| `comments` | `Comment[]` | Controlled comments. Pair with `onCommentsChange`. |
| `onCommentsChange` | `(comments) => void` | Fires on any comment mutation. Mirror into Y.Array for live sync. |
| `onCommentAdd` / `onCommentResolve` / `onCommentDelete` / `onCommentReply` | callbacks | Granular events when you want to log or trigger side effects, not own state. |

```tsx
const [comments, setComments] = useState<Comment[]>([]);

<DocxEditor
  documentBuffer={buf}
  author="Jess Lin"
  comments={comments}
  onCommentsChange={setComments}
/>;
```

<AuthorDemo />

For Yjs-backed sync, see [Realtime collaboration](/docs/1.x/realtime-collaboration).

## Toolbar and chrome

Toggle the built-in UI on or off.

| Prop | Type | Default | Description |
|---|---|---|---|
| `showToolbar` | `boolean` | `true` | Toolbar visibility. Pass `false` and compose your own from `/ui`. |
| `showZoomControl` | `boolean` | `true` | Bottom-right zoom widget. |
| `showRuler` | `boolean` | `false` | Page ruler above the document body. |
| `rulerUnit` | `"inch" \| "cm"` | `"inch"` | Ruler unit. |
| `showMarginGuides` | `boolean` | `false` | Faint guides at page margins. |
| `marginGuideColor` | `string` | `"#c0c0c0"` | CSS color for the guides above. |
| `showOutline` | `boolean` | `false` | Document outline / table of contents drawer. |
| `showOutlineButton` | `boolean` | `true` | Outline toggle button in the toolbar. |
| `initialZoom` | `number` | `1.0` | Starting zoom (`1.0` = 100%). |

The font picker and custom font registration have their own section below.

```tsx
// Headless-feeling editor: drop chrome and compose your own.
<DocxEditor documentBuffer={buf} showToolbar={false} showZoomControl={false} />
```

<UIControlsDemo />

## Fonts

`fontFamilies` controls what the toolbar dropdown offers. `fonts` (added in 1.1.0) registers the actual font faces so the editor can render and measure them. They are independent: list a family in `fontFamilies` to make it pickable, register it with `fonts` so its glyphs paint correctly.

| Prop | Type | Default | Description |
|---|---|---|---|
| `fonts` | `ReadonlyArray<FontDefinition>` | none | Custom font faces to register before the editor measures text. Each entry injects one `@font-face`. |
| `fontFamilies` | `ReadonlyArray<string \| FontOption>` | built-in 12 | Constrain the font picker to a specific list. |
| `onFontsLoaded` | `() => void` | none | Fires once the registered faces are ready. |

A `FontDefinition` is `{ family, src, weight? }`. `src` is a URL to a `woff2`/`woff`/`ttf`/`otf` file you host. Register multiple weights of the same family as separate entries that share `family`:

```tsx
import { DocxEditor } from "@eigenpal/docx-editor-react";

const FONTS = [
  { family: "Custom Sans", src: "/fonts/CustomSans-Regular.woff2" },
  { family: "Custom Sans", src: "/fonts/CustomSans-Bold.woff2", weight: 700 },
];

<DocxEditor
  documentBuffer={buf}
  fonts={FONTS}
  fontFamilies={["Custom Sans", "Arial", "Times New Roman"]}
/>;
```

Pass a stable reference (module-level or memoized). Inline arrays re-register on every render; the loader dedupes by `family|weight|style` so it's harmless, but it wastes work.

Font-load failures route through `onError` (see [Callbacks](#callbacks)), so you can forward them to your own tracker. With no `onError` attached they fall back to `console.warn`.

For host code that isn't using the React or Vue adapter, `@eigenpal/docx-editor-core/utils` exports `loadFontFromUrl`, `loadFontDefinitions`, `onFontError`, and the `FontDefinition` type so you can drive the same registration directly.

## Title bar customization

The header strip is fully overridable.

| Prop | Type | Description |
|---|---|---|
| `documentName` | `string` | Display name in the title bar. |
| `onDocumentNameChange` | `(name) => void` | Fires when the user edits the title in-place. |
| `documentNameEditable` | `boolean` | Default `true`. Set `false` to lock the title. |
| `renderLogo` | `() => ReactNode` | Left-side logo slot. Default renders the document icon. |
| `renderTitleBarRight` | `() => ReactNode` | Right-side slot. Wire your save status, share button, avatars. |
| `toolbarExtra` | `ReactNode` | Extra items appended to the toolbar. |

```tsx
<DocxEditor
  documentBuffer={buf}
  documentName={file.name}
  onDocumentNameChange={(name) => updateMetadata({ name })}
  renderTitleBarRight={() => <SaveIndicator dirty={dirty} />}
/>;
```

## Callbacks

Lifecycle and integration hooks.

| Prop | Type | Description |
|---|---|---|
| `onChange` | `(doc: Document) => void` | Fires on every document mutation. Throttle for autosave. |
| `onSave` | `(buf: ArrayBuffer) => void` | Fires when the user invokes Save (Cmd+S or toolbar). |
| `onSelectionChange` | `(state: SelectionState \| null) => void` | Selection metadata for custom UI (active marks, paragraph style, etc.). |
| `onError` | `(error: Error) => void` | Errors during parse or render. Send to your error tracker. |
| `onFontsLoaded` | `() => void` | Fired once the font set is ready. Use to defer measurement-sensitive UI. |
| `onPrint` / `onCopy` / `onCut` / `onPaste` | `() => void` | Notification hooks for clipboard and print events. |

```tsx
<DocxEditor
  documentBuffer={buf}
  onChange={(doc) => debouncedAutosave(doc)}
  onSave={async (buf) => {
    await fetch("/api/documents/1", { method: "PUT", body: buf });
  }}
  onError={(err) => reportError(err)}
/>;
```

## Styling

| Prop | Type | Description |
|---|---|---|
| `theme` | `Theme \| null` | Color and density token overrides. |
| `className` | `string` | Applied to the editor root element. |
| `style` | `CSSProperties` | Inline styles on the root. |
| `placeholder` | `ReactNode` | Rendered while there's no document content. |
| `loadingIndicator` | `ReactNode` | Rendered while the buffer is being parsed. |
| `printOptions` | `PrintOptions` | Margins, header/footer toggles for the print pipeline. |

```tsx
<DocxEditor
  documentBuffer={buf}
  className="rounded-lg shadow-md"
  loadingIndicator={<Spinner label="Loading document" />}
  placeholder={<EmptyState />}
/>;
```

## i18n

| Prop | Type | Description |
|---|---|---|
| `i18n` | `LocaleStrings \| PartialLocaleStrings` | Locale data from `@eigenpal/docx-editor-i18n`. See [i18n page](/docs/1.x/i18n). |

```tsx
import pl from "@eigenpal/docx-editor-i18n/pl";

<DocxEditor documentBuffer={buf} i18n={pl} />;
```

## Agents

| Prop | Type | Description |
|---|---|---|
| `agentPanel` | `AgentPanelOptions` | Wires a side panel slot. Pair with `useDocxAgentTools`. |

```tsx
<DocxEditor
  ref={editorRef}
  documentBuffer={buf}
  agentPanel={{ render: () => <AgentChatLog messages={messages} /> }}
/>;
```

Full setup in [Agents → Live editor](/docs/1.x/agents/live-editor).

## Plugins

| Prop | Type | Description |
|---|---|---|
| `externalPlugins` | `Plugin[]` | ProseMirror plugins appended to the editor's plugin list. |
| `pluginOverlays` | `ReactNode` | Absolutely-positioned overlay slot for plugin UI. |
| `pluginSidebarItems` | `ReactSidebarItem[]` | Sidebar entries contributed by plugins. |
| `pluginRenderedDomContext` | `RenderedDomContext \| null` | Hand-off when you need plugin code to read editor DOM measurements. |

See [Plugins](/docs/1.x/plugins) for the full plugin contract.

## Ref methods

Imperative API exposed through `forwardRef`. Capture a `DocxEditorRef` and call methods directly when you need to drive the editor from outside React state.

```tsx
import { useRef } from "react";
import { DocxEditor, type DocxEditorRef } from "@eigenpal/docx-editor-react";

const ref = useRef<DocxEditorRef>(null);

ref.current?.addComment({ paraId: "ABC12300", text: "Tighten this paragraph." });
ref.current?.scrollToParaId("DEF45600");
ref.current?.save(); // → ArrayBuffer
```

Common methods:

| Method | Returns | What it does |
|---|---|---|
| `save()` | `Promise<ArrayBuffer>` | Serialize the current document to a `.docx` buffer. |
| `addComment({ paraId, text })` | `Comment` | Add a comment anchored to a paragraph by `w14:paraId`. |
| `proposeChange({ paraId, ... })` | `void` | Insert a tracked change. |
| `findInDocument(query)` | `FindMatch[]` | Search the document. |
| `scrollToParaId(paraId)` | `boolean` | Scroll to a paragraph by `w14:paraId`. Returns false if not found. |
| `scrollToPosition(pos)` | `void` | Scroll to a raw ProseMirror position. |
| `getDocument()` | `Document` | Snapshot of the parsed tree. |

The full method list with signatures is at [/docs/1.x/api/react](/docs/1.x/api/react).

## See also

- [React quickstart](/docs/1.x/react)
- [React examples](/docs/1.x/react/examples)
- [Migration: API renames](/docs/1.x/migration#api-renames) for the `FormattingBar` → `Toolbar` and `Toolbar` → `EditorToolbar` shifts
- [Full API reference](/docs/1.x/api/react)

---

# Realtime Collaboration

Source: https://www.docx-editor.dev/docs/1.x/realtime-collaboration

Add live multi-user editing, cursors, presence, comment sync, tracked-change attribution, by binding `DocxEditor` to a [Yjs](https://github.com/yjs/yjs) document.

**Try it in 30 seconds:** open the [collaboration demo](/editor?collaborate=1), share the URL with a tab or a colleague. (Or visit the [online editor](/editor) and click **Collaborate**.)

## How it works

The editor exposes three props that hand off state to a CRDT:

| Prop | What it does |
| --- | --- |
| `externalContent` | Skip the built-in document loader. Yjs will populate the doc instead. |
| `externalPlugins` | Pass Yjs's ProseMirror plugins (`ySyncPlugin`, `yCursorPlugin`, `yUndoPlugin`). |
| `comments` + `onCommentsChange` | Controlled comment threads, mirrored to a Y.Array on the same Y.Doc. |

Tracked changes sync **for free**, they're ProseMirror marks, so `ySyncPlugin` carries them along with everything else.

## Step 1. Install

```bash
npm install yjs y-prosemirror y-webrtc
```

`y-webrtc` uses public free signaling and needs zero infra, perfect for getting started. We'll cover production providers (PartyKit, Liveblocks, Hocuspocus) below.

## Step 2. Set up a shared Y.Doc

```tsx
// useCollaboration.ts
import { useEffect, useState } from 'react';
import * as Y from 'yjs';
import { WebrtcProvider } from 'y-webrtc';
import { ySyncPlugin, yCursorPlugin, yUndoPlugin } from 'y-prosemirror';
import type { Plugin } from 'prosemirror-state';

export function useCollaboration(roomName: string, user: { name: string; color: string }) {
  // Hold the Y.Doc + provider in state, constructed inside an effect (not
  // useMemo). `new WebrtcProvider` registers the room in y-webrtc's module-
  // level map as a render-time side effect, if a render is aborted (e.g, a
  // CSP-blocked signaling socket throws, and an error boundary retries the
  // subtree), the first provider is never destroyed and the retry's second
  // `new WebrtcProvider(roomName, …)` throws "A Yjs Doc already exists for
  // room …". Pairing creation with cleanup inside an effect closes the gap.
  const [state, setState] = useState<{
    provider: WebrtcProvider;
    plugins: Plugin[];
  } | null>(null);

  useEffect(() => {
    const ydoc = new Y.Doc();
    const provider = new WebrtcProvider(roomName, ydoc);
    const fragment = ydoc.getXmlFragment('prosemirror');
    const plugins = [
      ySyncPlugin(fragment),                 // syncs the PM doc
      yCursorPlugin(provider.awareness),     // remote cursors
      yUndoPlugin(),                         // shared undo/redo
    ];
    setState({ provider, plugins });
    return () => {
      provider.destroy();
      ydoc.destroy();
      setState(null);
    };
  }, [roomName]);

  // Publish identity so peers can render avatars and labelled cursors.
  useEffect(() => {
    state?.provider.awareness.setLocalStateField('user', user);
  }, [state, user.name, user.color]);

  return state?.plugins ?? null;
}
```

The hook returns `null` until the provider is ready, guard the editor render on it (shown in Step 3).

## Step 3. Pass it to DocxEditor

```tsx
import { DocxEditor, createEmptyDocument } from '@eigenpal/docx-editor-react';
import { useCollaboration } from './useCollaboration';

export function CollaborativeEditor({ room, user }) {
  const plugins = useCollaboration(room, user);

  // Hold the editor mount until the Y.Doc + provider are ready, ySyncPlugin
  // has to attach on initial EditorState construction, swapping plugins in
  // later doesn't repopulate the doc.
  if (!plugins) return <div>Joining room…</div>;

  return (
    <DocxEditor
      document={createEmptyDocument()}  // schema seed. Yjs owns the content
      externalContent
      externalPlugins={plugins}
      author={user.name}
      showToolbar
      showRuler
    />
  );
}
```

Open the page in two tabs with the same `room`, type in one, watch the other update with a labelled cursor showing the remote user's color.

## Adding comment sync

Comment threads (text, replies, resolved status) live **outside** the PM doc. Mirror them through the controlled `comments` API to a Y.Array on the same Y.Doc:

```tsx
import { useCallback, useEffect, useState } from 'react';
import type { Comment } from '@eigenpal/docx-editor-core';

// Extend the setup effect from Step 2, create the Y.Array alongside plugins
// and hand it out through the same state object:
//   const yComments = ydoc.getArray<Comment>('comments');
//   setState({ provider, plugins, ydoc, yComments });

// Mirror Y.Array → React state (runs when `state` becomes non-null).
const [comments, setCommentsState] = useState<Comment[]>([]);
useEffect(() => {
  if (!state) return;
  const { yComments } = state;
  const sync = () => setCommentsState(yComments.toArray());
  sync();
  yComments.observeDeep(sync);
  return () => yComments.unobserveDeep(sync);
}, [state]);

// Push React state → Y.Array
const setComments = useCallback((next: Comment[]) => {
  if (!state) return;
  const { ydoc, yComments } = state;
  ydoc.transact(() => {
    yComments.delete(0, yComments.length);
    yComments.push(next);
  });
}, [state]);
```

Then pass to the editor:

```tsx
<DocxEditor
  /* …other props… */
  comments={comments}
  onCommentsChange={setComments}
/>
```

> **Production tip:** the snippet above replaces the entire array on every change. For high-concurrency rooms, store comments in a `Y.Map<commentId, Comment>` and apply diffs by id, avoids two users clobbering each other's edits.

## Production providers

`y-webrtc` is great for demos but needs no server, peers connect directly. For real apps you want a backed provider with persistence and access control:

| Provider | Best for | Swap |
| --- | --- | --- |
| [`y-partykit`](https://docs.partykit.io/reference/y-partykit-api/) (Cloudflare) | Edge-hosted rooms with storage | `new YPartyKitProvider(host, room, ydoc)` |
| [`@liveblocks/yjs`](https://liveblocks.io/docs/api-reference/liveblocks-yjs) | Managed presence + auth | `new LiveblocksYjsProvider(room, ydoc)` |
| [`@hocuspocus/provider`](https://tiptap.dev/docs/hocuspocus) | Self-hosted Node.js server | `new HocuspocusProvider({ url, name, document })` |
| `y-websocket` | Roll-your-own WebSocket server | `new WebsocketProvider(url, room, ydoc)` |

All four are drop-in replacements for `WebrtcProvider`, every other line of the hook stays the same. For example, switching to PartyKit means installing `y-partykit partysocket`, deploying a tiny `party/server.ts` that delegates to `y-partykit`'s `onConnect`, and changing one line in the hook:

```ts
import YPartyKitProvider from 'y-partykit/provider';
const provider = new YPartyKitProvider('docx-collab.your-account.partykit.dev', roomName, ydoc);
```

## Full example

A complete runnable example, full hook, AvatarStack, identity helper, App.tsx wiring, lives in the docx-editor monorepo:

> [examples/collaboration on GitHub](https://github.com/eigenpal/docx-editor/tree/main/examples/collaboration)

The same code powers the **Collaborate** button in the [online editor](/editor) on this site. Direct deep-link: [/editor?collaborate=1](/editor?collaborate=1).

---

# Vue Examples

Source: https://www.docx-editor.dev/docs/1.x/vue/examples

Drop-in components for the common patterns. Each is self-contained; swap the data source for your own.

## Load a document from a URL

```vue
<script setup lang="ts">
import { ref, watchEffect } from "vue";
import { DocxEditor } from "@eigenpal/docx-editor-vue";
import "@eigenpal/docx-editor-vue/styles.css";

const props = defineProps<{ url: string }>();
const buf = ref<ArrayBuffer | null>(null);

watchEffect(async () => {
  buf.value = await fetch(props.url).then((r) => r.arrayBuffer());
});
</script>

<template>
  <DocxEditor :document-buffer="buf" />
</template>
```

<DemoPlayground />

## Load from a file input

```vue
<script setup lang="ts">
import { ref } from "vue";
import { DocxEditor } from "@eigenpal/docx-editor-vue";

const buf = ref<ArrayBuffer | null>(null);

async function onFile(e: Event) {
  const file = (e.target as HTMLInputElement).files?.[0];
  if (file) buf.value = await file.arrayBuffer();
}
</script>

<template>
  <input type="file" accept=".docx" @change="onFile" />
  <DocxEditor v-if="buf" :document-buffer="buf" />
</template>
```

## Autosave on change

```vue
<script setup lang="ts">
import { useTemplateRef } from "vue";
import { DocxEditor, type DocxEditorRef } from "@eigenpal/docx-editor-vue";

const props = defineProps<{ docId: string }>();
const editor = useTemplateRef<DocxEditorRef>("editor");

let timer: number | null = null;
function onChange() {
  if (timer !== null) window.clearTimeout(timer);
  timer = window.setTimeout(async () => {
    const buf = await editor.value?.save();
    if (!buf) return;
    await fetch(`/api/documents/${props.docId}`, { method: "PUT", body: buf });
  }, 1500);
}
</script>

<template>
  <DocxEditor ref="editor" :document-buffer="null" @change="onChange" />
</template>
```

## Controlled comments

```vue
<script setup lang="ts">
import { ref } from "vue";
import { DocxEditor } from "@eigenpal/docx-editor-vue";
import type { Comment } from "@eigenpal/docx-editor-core";

defineProps<{ buf: ArrayBuffer; author: string }>();
const comments = ref<Comment[]>([]);

async function persist(next: Comment[]) {
  comments.value = next;
  await fetch("/api/comments", {
    method: "PUT",
    body: JSON.stringify(next),
    headers: { "content-type": "application/json" },
  });
}
</script>

<template>
  <DocxEditor
    :document-buffer="buf"
    :author="author"
    :comments="comments"
    @comments-change="persist"
  />
</template>
```

## Suggesting mode

```vue
<script setup lang="ts">
import { ref } from "vue";
import { DocxEditor, type EditorMode } from "@eigenpal/docx-editor-vue";

defineProps<{ buf: ArrayBuffer; reviewer: string }>();
const mode = ref<EditorMode>("suggesting");
</script>

<template>
  <DocxEditor
    :document-buffer="buf"
    :author="reviewer"
    :mode="mode"
    @mode-change="(m) => (mode = m)"
  />
</template>
```

<ModeToggleDemo />

As of 1.1.0 suggesting mode tracks more than inline text edits: paragraph breaks, paragraph-property changes, table row/cell insert/delete/merge, inserted and deleted images, and list/numbering changes are all recorded as real revisions, shown in the tracked-changes sidebar, and round-tripped to Word's `<w:ins>` / `<w:del>` markup. Accept-all and reject-all resolve every revision type.

## Custom fonts

Register self-hosted font files so the editor renders and measures them, then list the families in the picker. `:fonts` injects the `@font-face` rules; `:font-families` controls the toolbar dropdown. Added in 1.1.0.

```vue
<script setup lang="ts">
import { DocxEditor } from "@eigenpal/docx-editor-vue";

defineProps<{ buf: ArrayBuffer }>();

// Declared once in setup so the array identity stays stable.
const fonts = [
  { family: "Inter", src: "/fonts/Inter-Regular.woff2" },
  { family: "Inter", src: "/fonts/Inter-Bold.woff2", weight: 700 },
  { family: "JetBrains Mono", src: "/fonts/JetBrainsMono-Regular.woff2" },
];
const fontFamilies = ["Inter", "JetBrains Mono", "Arial", "Times New Roman"];
</script>

<template>
  <DocxEditor
    :document-buffer="buf"
    :fonts="fonts"
    :font-families="fontFamilies"
    @error="(err) => console.error('font or parse error', err)"
  />
</template>
```

Each `FontDefinition` is `{ family, src, weight? }`, where `src` points at a `woff2`/`woff`/`ttf`/`otf` file you serve. The paths above (`/fonts/...`) resolve against your site root, so drop the files in your static directory (`public/` in Vite or a Nuxt app). Register multiple weights of one family as separate entries that share `family`. Font-load failures surface through the `@error` event (falling back to `console.warn` when no listener is attached).

## Read-only viewer

```vue
<script setup lang="ts">
import { DocxEditor } from "@eigenpal/docx-editor-vue";

defineProps<{ buf: ArrayBuffer }>();
</script>

<template>
  <DocxEditor
    :document-buffer="buf"
    read-only
    :show-toolbar="false"
    :show-zoom-control="false"
  />
</template>
```

<ReadOnlyDemo />

## Realtime collaboration (Yjs)

```vue
<script setup lang="ts">
import { ref, onUnmounted } from "vue";
import * as Y from "yjs";
import { WebrtcProvider } from "y-webrtc";
import { ySyncPlugin, yCursorPlugin, yUndoPlugin } from "y-prosemirror";
import { DocxEditor } from "@eigenpal/docx-editor-vue";
import type { Comment } from "@eigenpal/docx-editor-core";

defineProps<{ buf: ArrayBuffer }>();
const ydoc = new Y.Doc();
const provider = new WebrtcProvider("room-1", ydoc);
const yXml = ydoc.getXmlFragment("docx");
const yComments = ydoc.getArray<Comment>("comments");

const plugins = [ySyncPlugin(yXml), yCursorPlugin(provider.awareness), yUndoPlugin()];
const comments = ref<Comment[]>(yComments.toArray());

yComments.observe(() => {
  comments.value = yComments.toArray();
});

function onCommentsChange(next: Comment[]) {
  ydoc.transact(() => {
    yComments.delete(0, yComments.length);
    yComments.push(next);
  });
}

onUnmounted(() => provider.destroy());
</script>

<template>
  <DocxEditor
    :document-buffer="buf"
    :external-plugins="plugins"
    :comments="comments"
    @comments-change="onCommentsChange"
  />
</template>
```

Full provider walkthrough (y-webrtc, PartyKit, Liveblocks) on [Realtime collaboration](/docs/1.x/realtime-collaboration).

## Agent panel

```vue
<script setup lang="ts">
import { useTemplateRef } from "vue";
import { DocxEditor, type DocxEditorRef } from "@eigenpal/docx-editor-vue";
import {
  AgentChatLog,
  AgentComposer,
  useDocxAgentTools,
} from "@eigenpal/docx-editor-agents/vue";
import { useChat } from "@ai-sdk/vue";

defineProps<{ buf: ArrayBuffer }>();
const editor = useTemplateRef<DocxEditorRef>("editor");
const { tools } = useDocxAgentTools({ editorRef: editor });
const chat = useChat({ api: "/api/agent-chat", body: { tools } });
</script>

<template>
  <DocxEditor ref="editor" :document-buffer="buf">
    <template #agentPanel>
      <AgentChatLog :messages="chat.messages" />
      <AgentComposer @submit="chat.sendMessage" />
    </template>
  </DocxEditor>
</template>
```

Server-side route + setup in [Agents → Live editor](/docs/1.x/agents/live-editor).

<AgentChatDemo />

## See also

- [Vue props](/docs/1.x/vue/props)
- [Vue API reference](/docs/1.x/api/vue)
- [React examples](/docs/1.x/react/examples), identical patterns for cross-reference

---

# 1.x/vue/index

Source: https://www.docx-editor.dev/docs/1.x/vue/index

<PackageStats name="@eigenpal/docx-editor-vue" />

## Status

`@eigenpal/docx-editor-vue` is new in the 1.0 release and currently in **beta**. The package targets Vue 3. Its surface mirrors the React adapter one-to-one: same component name, same subpath layout, same plugin contract. If you've shipped against `@eigenpal/docx-editor-react`, the Vue package is a port, not a learning curve.

## Install

```bash
npm install @eigenpal/docx-editor-vue
```

Pulls in `@eigenpal/docx-editor-core` and `@eigenpal/docx-editor-i18n`.

## Quickstart

```vue
<script setup lang="ts">
import { ref } from "vue";
import { DocxEditor } from "@eigenpal/docx-editor-vue";
import "@eigenpal/docx-editor-vue/styles.css";

const buf = ref<ArrayBuffer | null>(null);
</script>

<template>
  <DocxEditor :document-buffer="buf" />
</template>
```

## Using with Nuxt

For Nuxt 3 and 4, install [`@eigenpal/nuxt-docx-editor`](/docs/1.x/vue/nuxt), the official Nuxt module. It wraps this adapter and auto-imports an SSR-safe `<DocxEditor>`, so there's no `<ClientOnly>` wrapper to write:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ["@eigenpal/nuxt-docx-editor"],
});
```

See [Nuxt](/docs/1.x/vue/nuxt) for the module options and what to import from the adapter directly.

## Subpaths

- `@eigenpal/docx-editor-vue`: `<DocxEditor>`, `EditorMode`, `DocxEditorProps`, `i18nPlugin`, `provideLocale`
- `@eigenpal/docx-editor-vue/composables`: Vue equivalents of the React hooks (`useDocxEditor`, `useHistory`, `useAutoSave`, `useTrackedChanges`, etc.)
- `@eigenpal/docx-editor-vue/dialogs`: hyperlink, find/replace, paste special, page setup
- `@eigenpal/docx-editor-vue/plugin-api`: plugin host
- `@eigenpal/docx-editor-vue/styles`: CSS

Vue 1.0 does not yet ship the UI primitives that React's `/ui` does (`Toolbar`, `EditorToolbar`, pickers). Compose your own with the dialogs, composables, and your design system, or use the editor's built-in toolbar (rendered when no slot is provided). Vue UI primitives are tracked for 1.1.

Every export is in the [Vue API reference](/docs/1.x/api/vue).

## Parity with React

Upstream's `etc/parity.contract.json` lists every public symbol shipped under either adapter, with explicit buckets for paired, deferred, and exclusive. A CI step walks both packages' `.d.ts` and fails when the contract drifts. So anything in [/docs/1.x/api/react](/docs/1.x/api/react) has a matching entry in [/docs/1.x/api/vue](/docs/1.x/api/vue) with the same name and behavior. File an issue if you find a gap.

## Agent integration

Same toolkit, Vue subpath:

```ts
import { useDocxAgentTools } from "@eigenpal/docx-editor-agents/vue";
```

Composable instead of a hook. Same 14 tools, same transport. Server side is identical (`@eigenpal/docx-editor-agents/ai-sdk/server`).

## Where to next

- [Vue API reference](/docs/1.x/api/vue)
- [Migration: 0.x → 1.x](/docs/1.x/migration) if you ran the React adapter inside a Vue wrapper before
- [Plugins](/docs/1.x/plugins)

---

# @eigenpal/nuxt-docx-editor

Source: https://www.docx-editor.dev/docs/1.x/vue/nuxt

<PackageStats name="@eigenpal/nuxt-docx-editor" />

`@eigenpal/nuxt-docx-editor` is the official Nuxt module. It wraps [`@eigenpal/docx-editor-vue`](/docs/1.x/vue) and registers an SSR-safe `<DocxEditor>` as an auto-imported component, so a Nuxt app needs no manual import, no `<ClientOnly>` wrapper, and no Vite config. It supports Nuxt 3 and Nuxt 4.

For a step-by-step walkthrough with loading, saving, tracked changes, and collaboration, see the [Nuxt DOCX editor guide](/blog/nuxt-docx-editor).

## Install

```bash
npm install @eigenpal/nuxt-docx-editor
```

Pulls in `@eigenpal/docx-editor-vue`, and transitively `@eigenpal/docx-editor-core` and `@eigenpal/docx-editor-i18n`.

## Register the module

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ["@eigenpal/nuxt-docx-editor"],
});
```

That is the whole setup. The module registers `<DocxEditor>` as a client-only component and pushes the editor stylesheet into Nuxt's CSS pipeline.

## Use the component

```vue
<script setup lang="ts">
import { ref } from "vue";

const buf = ref<ArrayBuffer | null>(null);
</script>

<template>
  <DocxEditor :document-buffer="buf" />
</template>
```

No import, no `<ClientOnly>`. `<DocxEditor>` is the Vue adapter's component, registered unchanged: the same props (`document-buffer`, `mode`, `show-toolbar`, `external-plugins`, and the rest), events, and `DocxEditorRef` methods as [`@eigenpal/docx-editor-vue`](/docs/1.x/vue). The full prop list is on [Vue props](/docs/1.x/vue/props). It renders in the browser only (ProseMirror measures DOM geometry at mount), so Nuxt shows a placeholder during SSR and hydrates the editor on the client.

## Load a document

`document-buffer` takes an `ArrayBuffer`. A `null` buffer mounts an empty document; assign a real buffer to load a `.docx`. Here is a file picker that lets users open their own documents, with `@error` wired for unreadable input:

```vue
<script setup lang="ts">
import { ref } from "vue";

const buf = ref<ArrayBuffer | null>(null);

async function onFile(e: Event) {
  const file = (e.target as HTMLInputElement).files?.[0];
  if (file) buf.value = await file.arrayBuffer();
}
</script>

<template>
  <input type="file" accept=".docx" @change="onFile" />
  <DocxEditor
    v-if="buf"
    :document-buffer="buf"
    @error="(err) => console.error(err)"
  />
</template>
```

To save, call `save()` on the component's `DocxEditorRef`; it returns an `ArrayBuffer` of OOXML bytes, the same format the editor reads. The [Nuxt DOCX editor guide](/blog/nuxt-docx-editor) covers loading from a URL, saving to a download or a Nitro route, tracked changes, and collaboration.

## Options

```ts
export default defineNuxtConfig({
  modules: ["@eigenpal/nuxt-docx-editor"],
  docxEditor: {
    prefix: "Ep",
    injectStyles: true,
  },
});
```

| Option | Type | Default | Description |
|---|---|---|---|
| `prefix` | `string` | `''` | Component name prefix. `Ep` registers `<EpDocxEditor>`. |
| `injectStyles` | `boolean` | `true` | Pushes `@eigenpal/docx-editor-vue/styles.css` into `nuxt.options.css`. Set `false` to import the stylesheet yourself. |

## Composables

Every composable from `@eigenpal/docx-editor-vue/composables` (`useDocxEditor`, `useTrackedChanges`, `useFindReplace`, `useAutoSave`, and the rest) is auto-imported. Use them in any page or component with no import.

## What the module does not re-export

The module re-exports the `<DocxEditor>` component and the composables, not the whole adapter. These come from `@eigenpal/docx-editor-vue` directly:

- the `DocxEditorProps` and `DocxEditorRef` types
- `renderAsync`, `createEmptyDocument`
- the `/ui`, `/dialogs`, and `/plugin-api` subpaths

If you use any of them, add the adapter to your own `dependencies` so the import is explicit:

```bash
npm install @eigenpal/docx-editor-vue
```

## Where to next

- [Nuxt DOCX editor guide](/blog/nuxt-docx-editor): full walkthrough with loading, saving, collaboration, and agents
- [Vue package overview](/docs/1.x/vue): the adapter the module wraps
- [Vue API reference](/docs/1.x/api/vue): auto-generated from the d.ts
- [Nuxt example on GitHub](https://github.com/eigenpal/docx-editor/tree/main/examples/nuxt)

---

# Props

Source: https://www.docx-editor.dev/docs/1.x/vue/props

The Vue adapter accepts the same props as React; the differences are Vue's kebab-case attribute binding and template refs in place of `useRef`. Anything documented under [React props](/docs/1.x/react/props) applies, this page focuses on the Vue-specific bits. Full generated reference: [/docs/1.x/api/vue](/docs/1.x/api/vue).

## Binding props

Camel-case in TS, kebab-case in the template. Bind with `:` for non-string values:

```vue
<script setup lang="ts">
import { ref } from "vue";
import { DocxEditor, type EditorMode } from "@eigenpal/docx-editor-vue";
import "@eigenpal/docx-editor-vue/styles.css";

const buf = ref<ArrayBuffer | null>(null);
const mode = ref<EditorMode>("editing");
</script>

<template>
  <DocxEditor
    :document-buffer="buf"
    :mode="mode"
    author="Jess Lin"
    :show-zoom-control="true"
    @mode-change="(m) => (mode = m)"
  />
</template>
```

Props that are React callbacks become Vue events. So `onModeChange` in React is `@mode-change` in Vue. Same payload shape.

## Template ref

Capture the editor ref with `useTemplateRef` (Vue 3.5+) or `ref="..."` + a `ref()`:

```vue
<script setup lang="ts">
import { useTemplateRef } from "vue";
import { DocxEditor, type DocxEditorRef } from "@eigenpal/docx-editor-vue";

const editor = useTemplateRef<DocxEditorRef>("editor");

async function save() {
  const buf = await editor.value?.save();
  if (buf) await fetch("/api/documents/1", { method: "PUT", body: buf });
}
</script>

<template>
  <button @click="save">Save</button>
  <DocxEditor ref="editor" :document-buffer="null" />
</template>
```

Methods on `DocxEditorRef` match React one-to-one (`save`, `addComment`, `proposeChange`, `findInDocument`, `scrollToParaId`, `scrollToPosition`, `getDocument`). See [React props](/docs/1.x/react/props#ref-methods) for the table.

## Props by group

The groupings under [React props](/docs/1.x/react/props) all apply identically. Quick map of the binding syntax for each group.

### Document input

```vue
<DocxEditor :document-buffer="buf" />
<!-- or, pre-parsed -->
<DocxEditor :document="parsed" />
```

### Mode and read-only

```vue
<DocxEditor :document-buffer="buf" :mode="mode" @mode-change="(m) => (mode = m)" />
<DocxEditor :document-buffer="buf" read-only />
```

<ModeToggleDemo />

### Comments and collaboration

```vue
<DocxEditor
  :document-buffer="buf"
  author="Jess Lin"
  :comments="comments"
  @comments-change="(next) => (comments = next)"
/>
```

<AuthorDemo />

### Toolbar and chrome

```vue
<DocxEditor
  :document-buffer="buf"
  :show-toolbar="false"
  :show-zoom-control="false"
  :initial-zoom="1.25"
/>
```

<UIControlsDemo />

### Fonts

`:font-families` controls what the toolbar dropdown offers. `:fonts` (added in 1.1.0) registers the actual font faces so the editor can render and measure them. A `FontDefinition` is `{ family, src, weight? }`, where `src` is a URL to a `woff2`/`woff`/`ttf`/`otf` file you host. Share `family` across entries to register multiple weights.

```vue
<script setup>
import { DocxEditor } from "@eigenpal/docx-editor-vue";

const fonts = [
  { family: "Custom Sans", src: "/fonts/CustomSans-Regular.woff2" },
  { family: "Custom Sans", src: "/fonts/CustomSans-Bold.woff2", weight: 700 },
];
</script>

<template>
  <DocxEditor
    :document-buffer="buf"
    :fonts="fonts"
    :font-families="['Custom Sans', 'Arial']"
  />
</template>
```

Keep the array reference stable (declared once in `setup`, not rebuilt inline) so faces aren't re-registered on every render. Font-load failures surface through the `@error` event; with no listener attached they fall back to `console.warn`.

### Title bar slots

Vue uses named slots in place of React's render-prop callbacks:

```vue
<DocxEditor :document-buffer="buf" document-name="Q3 Memo">
  <template #titleBarRight>
    <SaveIndicator :dirty="dirty" />
  </template>
</DocxEditor>
```

The slot names map directly to the React callback names: `renderLogo` → `#logo`, `renderTitleBarRight` → `#titleBarRight`.

### Callbacks become events

| React prop | Vue event |
|---|---|
| `onChange` | `@change` |
| `onSave` | `@save` |
| `onSelectionChange` | `@selection-change` |
| `onError` | `@error` |
| `onFontsLoaded` | `@fonts-loaded` |
| `onCommentAdd` | `@comment-add` |
| `onCommentResolve` | `@comment-resolve` |
| `onCommentDelete` | `@comment-delete` |
| `onCommentReply` | `@comment-reply` |
| `onPrint` / `onCopy` / `onCut` / `onPaste` | `@print` / `@copy` / `@cut` / `@paste` |
| `onModeChange` | `@mode-change` |
| `onDocumentNameChange` | `@document-name-change` |

```vue
<DocxEditor
  :document-buffer="buf"
  @change="onChange"
  @save="onSave"
  @error="reportError"
/>
```

### Styling

```vue
<DocxEditor
  :document-buffer="buf"
  class="rounded-lg shadow-md"
  :style="{ height: '80vh' }"
>
  <template #placeholder>
    <EmptyState />
  </template>
</DocxEditor>
```

### i18n

```vue
<script setup>
import pl from "@eigenpal/docx-editor-i18n/pl";
import { DocxEditor } from "@eigenpal/docx-editor-vue";
</script>

<template>
  <DocxEditor :document-buffer="buf" :i18n="pl" />
</template>
```

### Agents

```vue
<DocxEditor
  ref="editor"
  :document-buffer="buf"
  :agent-panel="{ render: () => h(AgentChatLog, { messages }) }"
/>
```

Or use the `#agentPanel` named slot if you prefer template syntax:

```vue
<DocxEditor :document-buffer="buf">
  <template #agentPanel>
    <AgentChatLog :messages="messages" />
  </template>
</DocxEditor>
```

Full agent wiring in [Agents → Live editor](/docs/1.x/agents/live-editor).

## See also

- [React props](/docs/1.x/react/props) for the full per-prop reference (identical semantics)
- [Vue examples](/docs/1.x/vue/examples)
- [Vue API reference](/docs/1.x/api/vue)
- [Migration: 0.x → 1.x](/docs/1.x/migration)

---