# DOCX Editor — full documentation

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

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

---

# DocxReviewer API

Source: https://www.docx-editor.dev/docs/agent-api

`@eigenpal/docx-editor-agents` — headless, Word-like API for AI document review.

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

## Quick Start

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

const reviewer = await DocxReviewer.fromBuffer(buffer, 'AI Reviewer');

// Read — plain text with paragraph indices for LLM prompts
const text = reviewer.getContentAsText();
// [0] (h1) Introduction
// [1] The liability cap is $50k per incident.
// [2] (table, row 1, col 1) Revenue ...

// Comment on a paragraph (anchors to whole paragraph)
reviewer.addComment(1, 'This cap seems too low.');

// Replace text (creates tracked change)
reviewer.replace(1, '$50k', '$500k');

// Or batch from an LLM JSON response
reviewer.applyReview({
  comments: [{ paragraphIndex: 1, text: 'Too low.' }],
  proposals: [{ paragraphIndex: 1, search: '$50k', replaceWith: '$500k' }],
});

// Export
const output = await reviewer.toBuffer();
```

## DocxReviewer Methods

Author is set once via `DocxReviewer.fromBuffer(buffer, 'Author Name')` — no need to repeat it on every call.

### Read

| Method | Description |
| --- | --- |
| `DocxReviewer.fromBuffer(buffer: ArrayBuffer, author?: string \| undefined): Promise<DocxReviewer>` | Create a reviewer from a DOCX file buffer. |
| `getContent(options?: GetContentOptions \| undefined): ContentBlock[]` | Get document content as structured blocks (headings, paragraphs, tables, lists). |
| `getContentAsText(options?: GetContentOptions \| undefined): string` | Get document content as plain text for LLM prompts. Each paragraph is prefixed with its index: `[0] text`, `[1] text`, etc. Table cells include position: `[5] (table, row 1, col 2) cell text`. Avoids JSON quote-escaping issues — LLMs can copy text verbatim. |

### Discover

| Method | Description |
| --- | --- |
| `getChanges(filter?: ChangeFilter \| undefined): ReviewChange[]` | Get all tracked changes in the document. |
| `getComments(filter?: CommentFilter \| undefined): ReviewComment[]` | Get all comments with their replies. |

### Comment

| Method | Description |
| --- | --- |
| `addComment(paragraphIndex: number, text: string): number` | Add a comment on a paragraph. |
| `addComment(options: AddCommentOptions): number` | _(overload)_ |
| `replyTo(commentId: number, text: string): number` | Reply to an existing comment. |
| `replyTo(commentId: number, options: ReplyOptions): number` | _(overload)_ |

### Propose Changes

| Method | Description |
| --- | --- |
| `replace(paragraphIndex: number, search: string, replaceWith: string): void` | Replace text in a paragraph. Creates a tracked change (deletion + insertion). |
| `replace(options: ProposeReplacementOptions): void` | _(overload)_ |
| `proposeInsertion(options: ProposeInsertionOptions): void` | Insert text as a tracked change. |
| `proposeDeletion(options: ProposeDeletionOptions): void` | Delete text as a tracked change. |

### Resolve

| Method | Description |
| --- | --- |
| `acceptChange(id: number): void` | Accept a tracked change by its revision ID. |
| `rejectChange(id: number): void` | Reject a tracked change by its revision ID. |
| `acceptAll(): number` | Accept all tracked changes. Returns count accepted. |
| `rejectAll(): number` | Reject all tracked changes. Returns count rejected. |

### Batch

| Method | Description |
| --- | --- |
| `applyReview(ops: BatchReviewOptions): BatchResult` | Apply multiple review operations in one call. Uses the reviewer's default author. Individual failures are collected, not thrown. |

### Export

| Method | Description |
| --- | --- |
| `toDocument(): Document` | Get the modified Document model. |
| `toBuffer(): Promise<ArrayBuffer>` | Serialize back to a DOCX buffer. Requires the original buffer. |

## Types

### GetContentOptions

| Field | Type | Description |
| --- | --- | --- |
| `fromIndex?` | `number` |  |
| `toIndex?` | `number` |  |
| `includeTrackedChanges?` | `boolean` | Annotate tracked changes inline. Default: true |
| `includeCommentAnchors?` | `boolean` | Annotate comments inline. Default: true |

### BatchReviewOptions

| Field | Type | Description |
| --- | --- | --- |
| `accept?` | `number[]` |  |
| `reject?` | `number[]` |  |
| `comments?` | `AddCommentOptions[]` |  |
| `replies?` | `(ReplyOptions & \{ commentId: number; \})[]` |  |
| `proposals?` | `ProposeReplacementOptions[]` |  |

### BatchResult

| Field | Type | Description |
| --- | --- | --- |
| `accepted` | `number` |  |
| `rejected` | `number` |  |
| `commentsAdded` | `number` |  |
| `repliesAdded` | `number` |  |
| `proposalsAdded` | `number` |  |
| `errors` | `BatchError[]` |  |

### BatchError

| Field | Type | Description |
| --- | --- | --- |
| `operation` | `string` |  |
| `id?` | `number` |  |
| `search?` | `string` |  |
| `error` | `string` |  |

### ReviewChange

| Field | Type | Description |
| --- | --- | --- |
| `id` | `number` |  |
| `type` | `'insertion' \| 'deletion' \| 'moveFrom' \| 'moveTo'` |  |
| `author` | `string` |  |
| `date` | `string \| null` |  |
| `text` | `string` |  |
| `context` | `string` |  |
| `paragraphIndex` | `number` |  |

### ReviewComment

| Field | Type | Description |
| --- | --- | --- |
| `id` | `number` |  |
| `author` | `string` |  |
| `date` | `string \| null` |  |
| `text` | `string` |  |
| `anchoredText` | `string` |  |
| `paragraphIndex` | `number` |  |
| `replies` | `ReviewCommentReply[]` |  |
| `done` | `boolean` |  |

### AddCommentOptions

| Field | Type | Description |
| --- | --- | --- |
| `paragraphIndex` | `number` |  |
| `text` | `string` |  |
| `author?` | `string` |  |
| `search?` | `string` | Optional: anchor to specific text. Omit to anchor whole paragraph. |

### ProposeReplacementOptions

| Field | Type | Description |
| --- | --- | --- |
| `paragraphIndex` | `number` |  |
| `search` | `string` |  |
| `replaceWith` | `string` |  |
| `author?` | `string` |  |

## Examples

### Next.js API Route — AI Document Review

Upload a DOCX, send it to an LLM for review, apply comments and tracked changes, return the modified file.

```ts
// app/api/review/route.ts
import { NextRequest, NextResponse } from 'next/server';
import OpenAI from 'openai';
import { DocxReviewer } from '@eigenpal/docx-editor-agents';

const openai = new OpenAI();

export async function POST(request: NextRequest) {
  const formData = await request.formData();
  const file = formData.get('file') as File;
  if (!file) return NextResponse.json({ error: 'No file' }, { status: 400 });

  // 1. Parse DOCX and read as plain text
  const reviewer = await DocxReviewer.fromBuffer(await file.arrayBuffer(), 'AI Reviewer');
  const text = reviewer.getContentAsText();

  // 2. Send to LLM
  const response = await openai.chat.completions.create({
    model: 'gpt-4o',
    response_format: { type: 'json_object' },
    messages: [
      {
        role: 'system',
        content: `Review this document. Return JSON:
{
  "comments": [{ "paragraphIndex": <number>, "text": "<feedback>" }],
  "replacements": [{ "paragraphIndex": <number>, "search": "<phrase>", "replaceWith": "<better>" }]
}
paragraphIndex must match a [number] from the document.`
      },
      { role: 'user', content: text }
    ],
  });

  const actions = JSON.parse(response.choices[0]?.message?.content || '{}');

  // 3. Apply review — author is set once on the reviewer
  reviewer.applyReview({
    comments: actions.comments,
    proposals: actions.replacements,
  });

  // 4. Return modified DOCX
  const output = await reviewer.toBuffer();
  return new NextResponse(output, {
    headers: {
      'Content-Type': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
    },
  });
}
```

### Node.js Script — Batch Review

Review multiple DOCX files from the command line.

```ts
import { readFileSync, writeFileSync } from 'fs';
import { DocxReviewer } from '@eigenpal/docx-editor-agents';

const buffer = readFileSync('contract.docx');
const reviewer = await DocxReviewer.fromBuffer(buffer.buffer, 'Legal Bot');

// Read content
const content = reviewer.getContentAsText();
console.log(content);
// [0] (h1) Service Agreement
// [1] The liability cap is $50k per incident.
// [2] (table, row 1, col 1) Party A ...

// Add comments and changes directly
reviewer.addComment(1, 'Liability cap is below industry standard.');
reviewer.replace(1, '$50k', '$500k');

// Export
const output = await reviewer.toBuffer();
writeFileSync('contract-reviewed.docx', Buffer.from(output));
```

### Using with Claude (Anthropic)

```ts
import Anthropic from '@anthropic-ai/sdk';
import { DocxReviewer } from '@eigenpal/docx-editor-agents';

const client = new Anthropic();
const reviewer = await DocxReviewer.fromBuffer(buffer, 'Claude Reviewer');

const response = await client.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 4096,
  messages: [{
    role: 'user',
    content: `Review this document and return JSON with comments and replacements:\n\n${reviewer.getContentAsText()}`
  }],
});

const actions = JSON.parse(response.content[0].text);
reviewer.applyReview({ comments: actions.comments, proposals: actions.replacements });
```

Full working example: [examples/agent-use-demo](https://github.com/eigenpal/docx-editor/tree/main/examples/agent-use-demo)

---

Source: [`@eigenpal/docx-editor-agents`](https://github.com/eigenpal/docx-editor/tree/main/packages/agent-use)

---

# Interactive Examples

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

## Playground

Try the full interactive playground to toggle props and see changes in real time:

<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 />

---

# Getting Started

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

## Overview

`@eigenpal/docx-js-editor` is an open-source WYSIWYG document editor for React that lets users edit `.docx` files directly in the browser. It provides a Word-like editing experience with rich formatting, tables, images, track changes, comments, and more — all client-side with no server required.

## Quick Install

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

Or with your preferred package manager:

```bash
# Yarn
yarn add @eigenpal/docx-js-editor

# pnpm
pnpm add @eigenpal/docx-js-editor

# Bun
bun add @eigenpal/docx-js-editor
```

## Minimal Setup

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

function App() {
  const [buffer, setBuffer] = useState<ArrayBuffer | null>(null);

  useEffect(() => {
    fetch('/template.docx')
      .then((res) => res.arrayBuffer())
      .then(setBuffer);
  }, []);

  if (!buffer) return <div>Loading...</div>;

  return (
    <DocxEditor
      documentBuffer={buffer}
      showToolbar={true}
      showRuler={true}
    />
  );
}
```

That's it — you now have a fully functional document editor in your React app.

## Try It Live

Toggle props and see the editor respond in real time:

<DemoPlayground />

## Key Features

- **Rich text editing** — bold, italic, underline, strikethrough, colors, fonts, sizes
- **Tables** — insert, resize, merge/split cells
- **Images** — insert, resize, drag-and-drop
- **Page layout** — margins, orientation, page breaks, headers/footers
- **Track changes** — suggesting mode with accept/reject
- **Comments** — add, reply, resolve
- **Zoom & rulers** — adjustable zoom level and document rulers
- **Customizable toolbar** — render props and compound component APIs
- **Plugin system** — extend with EditorPlugins (browser) and CorePlugins (Node.js)
- **Translations (i18n)** — localize the editor UI into any language, community contributions welcome
- **Export** — save back to `.docx` format

## Next Steps

- [Installation](/docs/installation) — framework-specific setup for Next.js, Vite, Remix, Astro, and Vue
- [Props Reference](/docs/props) — full list of configuration props and ref methods
- [Toolbar Customization](/docs/toolbar) — customize the toolbar with logos, actions, and extra buttons
- [Editor Modes](/docs/modes) — editing, suggesting, viewing, and read-only modes
- [Translations (i18n)](/docs/translations) — localize the editor UI into any language, [contribute a locale](/docs/translations#contributing-a-new-locale)
- [Examples](/docs/examples) — interactive demos with live prop toggling

---

# Installation

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

## Prerequisites

- **React 18+** (or React 19)
- **Node.js 18+**

## Install the Package

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

Don't forget to import the styles:

```tsx
import '@eigenpal/docx-js-editor/styles.css';
```

## Next.js

Use the editor in any `'use client'` component:

```tsx
// components/Editor.tsx
'use client';

import { DocxEditor } from '@eigenpal/docx-js-editor';
import '@eigenpal/docx-js-editor/styles.css';

export function Editor({ buffer }: { buffer: ArrayBuffer }) {
  return <DocxEditor documentBuffer={buffer} showToolbar />;
}
```

## Vite (React)

Works out of the box — no special configuration needed:

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

function App() {
  const [buffer, setBuffer] = useState<ArrayBuffer | null>(null);

  useEffect(() => {
    fetch('/template.docx')
      .then((res) => res.arrayBuffer())
      .then(setBuffer);
  }, []);

  if (!buffer) return <div>Loading...</div>;
  return <DocxEditor documentBuffer={buffer} showToolbar />;
}
```

## Remix

Use `ClientOnly` to prevent server rendering:

```tsx
import { ClientOnly } from 'remix-utils/client-only';
import { DocxEditor } from '@eigenpal/docx-js-editor';
import '@eigenpal/docx-js-editor/styles.css';

export default function EditorRoute() {
  const [buffer, setBuffer] = useState<ArrayBuffer | null>(null);

  useEffect(() => {
    fetch('/template.docx')
      .then((res) => res.arrayBuffer())
      .then(setBuffer);
  }, []);

  return (
    <ClientOnly fallback={<div>Loading editor...</div>}>
      {() => buffer && <DocxEditor documentBuffer={buffer} showToolbar />}
    </ClientOnly>
  );
}
```

## Astro

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

```astro
---
// src/pages/editor.astro
---
<html>
  <body>
    <EditorWrapper client:only="react" />
  </body>
</html>
```

```tsx
// src/components/EditorWrapper.tsx
import { useState, useEffect } from 'react';
import { DocxEditor } from '@eigenpal/docx-js-editor';
import '@eigenpal/docx-js-editor/styles.css';

export default function EditorWrapper() {
  const [buffer, setBuffer] = useState<ArrayBuffer | null>(null);

  useEffect(() => {
    fetch('/template.docx')
      .then((res) => res.arrayBuffer())
      .then(setBuffer);
  }, []);

  if (!buffer) return <div>Loading...</div>;
  return <DocxEditor documentBuffer={buffer} showToolbar />;
}
```

## Vue (via Web Component wrapper)

The editor is a React component, but you can wrap it for Vue using `@veaury/vue-react`:

```bash
npm install @eigenpal/docx-js-editor @veaury/vue-react react react-dom
```

```vue
<template>
  <ReactDocxEditor v-if="buffer" :documentBuffer="buffer" :showToolbar="true" />
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { applyReactInVue } from '@veaury/vue-react';
import { DocxEditor } from '@eigenpal/docx-js-editor';
import '@eigenpal/docx-js-editor/styles.css';

const ReactDocxEditor = applyReactInVue(DocxEditor);
const buffer = ref(null);

onMounted(async () => {
  const res = await fetch('/template.docx');
  buffer.value = await res.arrayBuffer();
});
</script>
```

## Example Repositories

Full working examples for each framework are available on GitHub:

- [Next.js Example](https://github.com/eigenpal/docx-js-editor/tree/main/examples/nextjs)
- [Vite Example](https://github.com/eigenpal/docx-js-editor/tree/main/examples/vite)
- [Remix Example](https://github.com/eigenpal/docx-js-editor/tree/main/examples/remix)
- [Astro Example](https://github.com/eigenpal/docx-js-editor/tree/main/examples/astro)

---

# Editor Modes

Source: https://www.docx-editor.dev/docs/modes

## Overview

The editor supports four modes that control how users interact with the document:

| Mode | Prop | Description |
| --- | --- | --- |
| **Editing** | `mode="editing"` | Full editing — changes are applied directly |
| **Suggesting** | `mode="suggesting"` | Track changes — edits are recorded as suggestions |
| **Viewing** | `mode="viewing"` | Read-only with toolbar visible — users can zoom, print, navigate |
| **Read-Only** | `readOnly={true}` | Minimal preview — no toolbar, no rulers, no interaction UI |

## Editing Mode

The default mode. Users can freely edit the document — type text, format, insert tables and images, etc. All changes are applied directly to the document.

```tsx
<DocxEditor
  documentBuffer={buffer}
  mode="editing"
/>
```

## Suggesting Mode

Enables track changes. All edits are recorded as insertions and deletions that can be accepted or rejected. This is useful for collaborative editing workflows.

```tsx
<DocxEditor
  documentBuffer={buffer}
  mode="suggesting"
  author="Jane Doe"
/>
```

The `author` prop sets who is credited for each tracked change. The toolbar shows accept/reject controls for suggestions.

## Viewing Mode

A read-only mode that keeps the toolbar visible. Users can zoom, print, navigate headings, and use the document outline — but they cannot edit content. This is the right choice for document review UIs where users still need toolbar controls.

```tsx
<DocxEditor
  documentBuffer={buffer}
  mode="viewing"
/>
```

## Read-Only Mode

The most minimal mode. Hides the toolbar, rulers, and all editing UI. The document is rendered as a static preview. Use this for embedding documents in pages where no interaction is needed.

```tsx
<DocxEditor
  documentBuffer={buffer}
  readOnly
/>
```

## Controlled Mode Switching

You can let users switch modes at runtime using `onModeChange`:

```tsx
function App() {
  const [mode, setMode] = useState<'editing' | 'suggesting' | 'viewing'>('editing');

  return (
    <div>
      <select value={mode} onChange={(e) => setMode(e.target.value as any)}>
        <option value="editing">Editing</option>
        <option value="suggesting">Suggesting</option>
        <option value="viewing">Viewing</option>
      </select>

      <DocxEditor
        documentBuffer={buffer}
        mode={mode}
        onModeChange={setMode}
        author="Jane Doe"
      />
    </div>
  );
}
```

The `onModeChange` callback fires when the user switches modes through the toolbar's built-in mode selector (if visible). Passing both `mode` and `onModeChange` makes it a controlled component.

## Mode Comparison

| Feature | Editing | Suggesting | Viewing | Read-Only |
| --- | --- | --- | --- | --- |
| Text editing | Yes | Yes (tracked) | No | No |
| Toolbar visible | Yes | Yes | Yes | No |
| Rulers | Configurable | Configurable | Configurable | No |
| Zoom controls | Yes | Yes | Yes | No |
| Print | Yes | Yes | Yes | No |
| Comments | Yes | Yes | View only | No |
| Track changes UI | No | Yes | View only | No |
| Document outline | Configurable | Configurable | Configurable | No |

---

# CorePlugin & Headless API

Source: https://www.docx-editor.dev/docs/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-js-editor/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/plugins/editor-plugins) instead.

## DocumentAgent

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

```ts
import { DocumentAgent } from '@eigenpal/docx-js-editor/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-js-editor/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-js-editor/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-js-editor';
import type { Document } from '@eigenpal/docx-js-editor';

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-js-editor';

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-js-editor';

// 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-js-editor';
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-js-editor';

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/plugins/editor-plugins) — browser-side UI plugins
- [Examples & Cookbook](/docs/plugins/examples) — advanced patterns
- [Getting Started](/docs/plugins/getting-started) — overview and hello world

---

# EditorPlugin API

Source: https://www.docx-editor.dev/docs/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-js-editor';

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-js-editor';
```

**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-js-editor/blob/main/docs/EXTENSIONS.md) for details.

---

# Plugin Examples & Cookbook

Source: https://www.docx-editor.dev/docs/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-js-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-js-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/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/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-js-editor';
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-js-editor';

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-js-editor';

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/plugins/editor-plugins) for the full reference including workarounds.

## Next Steps

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

---

# plugins/index

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

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

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

---

# Props & Ref Methods

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

The `DocxEditor` component accepts the following props, grouped by concern.

Source: [`DocxEditorProps`](https://github.com/eigenpal/docx-js-editor/blob/main/packages/react/src/components/DocxEditor.tsx)

## All Props

| Prop | Type | Default | Group |
| --- | --- | --- | --- |
| `documentBuffer` | `DocxInput \| null` | — | [Document Input](#document-input) |
| `document` | `Document \| null` | — | [Document Input](#document-input) |
| `author` | `string` | — | [Collaboration](#collaboration) |
| `mode` | `EditorMode` | `'editing'` | [Collaboration](#collaboration) |
| `onModeChange` | `(mode: EditorMode) => void` | — | [Collaboration](#collaboration) |
| `readOnly` | `boolean` | — | [Collaboration](#collaboration) |
| `onCommentAdd` | `(comment: Comment) => void` | — | [Collaboration](#collaboration) |
| `onCommentResolve` | `(comment: Comment) => void` | — | [Collaboration](#collaboration) |
| `onCommentDelete` | `(comment: Comment) => void` | — | [Collaboration](#collaboration) |
| `onCommentReply` | `(reply: Comment, parent: Comment) => void` | — | [Collaboration](#collaboration) |
| `externalContent` | `boolean` | — | [Collaboration](#collaboration) |
| `comments` | `Comment[]` | — | [Collaboration](#collaboration) |
| `onCommentsChange` | `(comments: Comment[]) => void` | — | [Collaboration](#collaboration) |
| `showToolbar` | `boolean` | `true` | [Toolbar & UI Controls](#toolbar-ui-controls) |
| `showZoomControl` | `boolean` | `true` | [Toolbar & UI Controls](#toolbar-ui-controls) |
| `showRuler` | `boolean` | `false` | [Toolbar & UI Controls](#toolbar-ui-controls) |
| `rulerUnit` | `'inch' \| 'cm'` | `'inch'` | [Toolbar & UI Controls](#toolbar-ui-controls) |
| `showMarginGuides` | `boolean` | `false` | [Toolbar & UI Controls](#toolbar-ui-controls) |
| `marginGuideColor` | `string` | `'#c0c0c0'` | [Toolbar & UI Controls](#toolbar-ui-controls) |
| `showOutline` | `boolean` | `false` | [Toolbar & UI Controls](#toolbar-ui-controls) |
| `showOutlineButton` | `boolean` | `true` | [Toolbar & UI Controls](#toolbar-ui-controls) |
| `showPrintButton` | `boolean` | `true` | [Toolbar & UI Controls](#toolbar-ui-controls) |
| `initialZoom` | `number` | `1.0` | [Toolbar & UI Controls](#toolbar-ui-controls) |
| `renderLogo` | `() => ReactNode` | — | [Title Bar Customization](#title-bar-customization) |
| `documentName` | `string` | — | [Title Bar Customization](#title-bar-customization) |
| `onDocumentNameChange` | `(name: string) => void` | — | [Title Bar Customization](#title-bar-customization) |
| `documentNameEditable` | `boolean` | `true` | [Title Bar Customization](#title-bar-customization) |
| `renderTitleBarRight` | `() => ReactNode` | — | [Title Bar Customization](#title-bar-customization) |
| `toolbarExtra` | `ReactNode` | — | [Title Bar Customization](#title-bar-customization) |
| `onChange` | `(document: Document) => void` | — | [Callbacks](#callbacks) |
| `onSave` | `(buffer: ArrayBuffer) => void` | — | [Callbacks](#callbacks) |
| `onSelectionChange` | `(state: SelectionState \| null) => void` | — | [Callbacks](#callbacks) |
| `onError` | `(error: Error) => void` | — | [Callbacks](#callbacks) |
| `onFontsLoaded` | `() => void` | — | [Callbacks](#callbacks) |
| `onPrint` | `() => void` | — | [Callbacks](#callbacks) |
| `onCopy` | `() => void` | — | [Callbacks](#callbacks) |
| `onCut` | `() => void` | — | [Callbacks](#callbacks) |
| `onPaste` | `() => void` | — | [Callbacks](#callbacks) |
| `theme` | `Theme \| null` | — | [Styling](#styling) |
| `className` | `string` | — | [Styling](#styling) |
| `style` | `CSSProperties` | — | [Styling](#styling) |
| `placeholder` | `ReactNode` | — | [Styling](#styling) |
| `loadingIndicator` | `ReactNode` | — | [Styling](#styling) |
| `printOptions` | `PrintOptions` | — | [Styling](#styling) |
| `fontFamilies` | `ReadonlyArray<string \| FontOption>` | — | Other |
| `i18n` | `Translations` | — | Other |

## Document Input

Pass your document data to the editor. Use `documentBuffer` for raw file data (most common), or `document` if you've already parsed it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `documentBuffer` | `DocxInput \| null` | — | Document data — ArrayBuffer, Uint8Array, Blob, or File |
| `document` | `Document \| null` | — | Pre-parsed document (alternative to documentBuffer) |

```tsx
<DocxEditor documentBuffer={arrayBuffer} />

{/* Or from a File input */}
const file = e.target.files[0];
<DocxEditor documentBuffer={file} />
```

## Collaboration

Set the current user's identity and control the editing mode. These props determine who is credited for comments and tracked changes, and whether edits are applied directly or recorded as suggestions.

### Author Identity

The `author` prop sets the name shown on comments and tracked changes. Without it, all contributions appear as **"User"**.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `author` | `string` | — | Author name used for comments and track changes |

```tsx
{/* Comments and suggestions will show "Dr. Jane Silva" */}
<DocxEditor
  documentBuffer={buf}
  author="Dr. Jane Silva"
/>
```

Pass it from your auth context:

```tsx
function App() {
  const { user } = useUser();

  return (
    <DocxEditor
      documentBuffer={buf}
      author={user.name}
      mode="suggesting"
    />
  );
}
```

<AuthorDemo />

### Editor Mode

Control how the editor behaves — direct editing, tracked suggestions, view-only, or fully read-only. Toggle between modes below to see the difference.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | `EditorMode` | `'editing'` | Editor mode: 'editing' (direct edits), 'suggesting' (track changes), or 'viewing' (read-only). |
| `onModeChange` | `(mode: EditorMode) => void` | — | Callback when the editing mode changes |
| `readOnly` | `boolean` | — | Whether the editor is read-only. When true, hides toolbar and rulers |

```tsx
{/* Controlled mode — e.g. enforce suggesting for junior editors */}
<DocxEditor
  documentBuffer={buf}
  mode={role === 'reviewer' ? 'suggesting' : 'editing'}
  onModeChange={(m) => setMode(m)}
  author={user.name}
/>

{/* Read-only document viewer (no toolbar, no caret) */}
<DocxEditor documentBuffer={buf} readOnly />
```

Passing both `mode` and `onModeChange` makes it a controlled component — the toolbar's built-in mode selector will call `onModeChange` instead of switching internally. See [Editor Modes](/docs/modes) for a full comparison of all four modes.

<ModeToggleDemo />

### Comments & Suggestions API

Comments and tracked changes are fully supported in the editor UI — users can add comments, reply, resolve, and accept/reject suggestions. The `author` prop controls attribution for all of these.

Use these callbacks to react to comment events — e.g. persist to your backend, sync across users, or log for audit:

| Prop | Type | Description |
| --- | --- | --- |
| `onCommentAdd` | `(comment: Comment) => void` | Callback when a comment is added via the UI |
| `onCommentResolve` | `(comment: Comment) => void` | Callback when a comment is resolved via the UI |
| `onCommentDelete` | `(comment: Comment) => void` | Callback when a comment is deleted via the UI |
| `onCommentReply` | `(reply: Comment, parent: Comment) => void` | Callback when a reply is added to a comment via the UI |

Each callback receives the full [`Comment`](https://github.com/eigenpal/docx-js-editor/blob/main/packages/core/src/types/content.ts) object with `id`, `author`, `date`, and `content`.

```tsx
<DocxEditor
  documentBuffer={buf}
  author={user.name}
  mode="suggesting"
  onCommentAdd={(comment) => {
    // comment: { id, author, date, content, parentId?, done? }
    saveComment(comment);
  }}
  onCommentResolve={(comment) => resolveComment(comment.id)}
  onCommentDelete={(comment) => deleteComment(comment.id)}
  onCommentReply={(reply, parent) => {
    saveReply(reply, parent.id);
  }}
/>
```

For **programmatic access** to comments and tracked changes (e.g. AI-powered review, batch operations, or server-side processing), use the [`DocxReviewer`](/docs/agent-api) API from the `@eigenpal/docx-editor-agents` package:

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

`DocxReviewer` gives you a Word-like API for reading, commenting, and proposing tracked changes — all headless, no browser required:

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

const reviewer = await DocxReviewer.fromBuffer(buffer, 'AI Reviewer');

// Read content as plain text (with paragraph indices for targeting)
const text = reviewer.getContentAsText();
// [0] (h1) Service Agreement
// [1] The liability cap is $50k per incident.

// Add a comment on a specific paragraph
reviewer.addComment(1, 'This clause needs review.');

// Propose a tracked change (shows as insertion + deletion)
reviewer.replace(1, '$50k', '$500k');

// Or batch everything from an LLM response
reviewer.applyReview({
  comments: [{ paragraphIndex: 1, text: 'Cap seems low.' }],
  proposals: [{ paragraphIndex: 1, search: '$50k', replaceWith: '$500k' }],
});

// Export back to .docx
const output = await reviewer.toBuffer();
```

The modified file can then be loaded into `<DocxEditor />` — comments and tracked changes render in the sidebar, ready for the user to accept or reject.

See the full [DocxReviewer API reference](/docs/agent-api) for all methods, types, and framework examples (Next.js, Node.js, Claude).

### Realtime Collaboration (Yjs)

Hand off ProseMirror state and comment storage to an external sync layer (Yjs, Liveblocks, Automerge…) for live multi-user editing with cursors, presence, comment threads, and tracked-change attribution.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `externalContent` | `boolean` | — | When true, the editor treats the `document` prop as a schema seed only and does not load it into ProseMirror on mount. Content is expected to come from external sources — typically `externalPlugins` such as `ySyncPlugin` from `y-prosemirror`, but also any code that dispatches transactions directly. You must still pass a `document` prop (e.g., `createEmptyDocument()`) so the editor can build its schema and render the shell. |
| `comments` | `Comment[]` | — | Controlled comments array. When provided, the editor reads comment thread metadata (text, author, replies, resolved status) from this prop instead of internal state, and emits every change through `onCommentsChange`. Use this with collaboration backends (Yjs, Liveblocks, Automerge, …) so comment threads sync across peers — the PM document only carries the range markers; thread metadata lives outside the doc and needs its own sync channel. If omitted, the editor falls back to internal state (current behavior). The granular `onCommentAdd`/`onCommentResolve`/`onCommentDelete`/ `onCommentReply` callbacks fire in both modes. |
| `onCommentsChange` | `(comments: Comment[]) => void` | — | Fires whenever the comments array changes (controlled mode). |

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

const ydoc = new Y.Doc();
const provider = new WebrtcProvider('my-room', ydoc);
const fragment = ydoc.getXmlFragment('prosemirror');
const plugins = [ySyncPlugin(fragment), yCursorPlugin(provider.awareness), yUndoPlugin()];

<DocxEditor
  document={createEmptyDocument()}   // schema seed only
  externalContent                    // Yjs owns the doc
  externalPlugins={plugins}
  comments={comments}                // controlled, mirrored from a Y.Array
  onCommentsChange={setComments}
  author={user.name}
/>
```

See the [Realtime Collaboration guide](/docs/realtime-collaboration) for a full y-webrtc walkthrough plus a production PartyKit (Cloudflare) setup, and the runnable [example](https://github.com/eigenpal/docx-editor/tree/main/examples/collaboration) in the docx-editor repo.

## Toolbar & UI Controls

Toggle editor chrome — toolbar, zoom slider, rulers, margin guides, outline sidebar, and print button. Try the checkboxes below to see each prop in action.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showToolbar` | `boolean` | `true` | Whether to show toolbar |
| `showZoomControl` | `boolean` | `true` | Whether to show zoom control |
| `showRuler` | `boolean` | `false` | Whether to show horizontal ruler |
| `rulerUnit` | `'inch' \| 'cm'` | `'inch'` | Unit for ruler display |
| `showMarginGuides` | `boolean` | `false` | Whether to show page margin guides/boundaries |
| `marginGuideColor` | `string` | `'#c0c0c0'` | Color for margin guides |
| `showOutline` | `boolean` | `false` | Whether to show the document outline sidebar |
| `showOutlineButton` | `boolean` | `true` | Whether to show the floating outline toggle button |
| `showPrintButton` | `boolean` | `true` | Whether to show print button in toolbar |
| `initialZoom` | `number` | `1.0` | Initial zoom level |

```tsx
<DocxEditor
  documentBuffer={buf}
  showToolbar
  showRuler
  rulerUnit="cm"
  showMarginGuides
  showOutline
  initialZoom={0.75}
/>

{/* Hide the floating outline button (e.g. in read-only embeds) */}
<DocxEditor documentBuffer={buf} showOutlineButton={false} />
```

<UIControlsDemo />

## Title Bar Customization

The title bar sits above the toolbar. Add your app logo, show the document name, and place custom actions on the right. Toggle the checkboxes to see each render prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `renderLogo` | `() => ReactNode` | — | Custom logo/icon for the title bar |
| `documentName` | `string` | — | Document name shown in the title bar |
| `onDocumentNameChange` | `(name: string) => void` | — | Callback when document name changes |
| `documentNameEditable` | `boolean` | `true` | Whether the document name is editable |
| `renderTitleBarRight` | `() => ReactNode` | — | Custom right-side actions for the title bar |
| `toolbarExtra` | `ReactNode` | — | Custom toolbar actions |

```tsx
<DocxEditor
  documentBuffer={buf}
  renderLogo={() => <img src="/logo.svg" alt="Logo" />}
  documentName="Quarterly Report"
  onDocumentNameChange={(name) => save(name)}
  renderTitleBarRight={() => (
    <button onClick={share}>Share</button>
  )}
/>
```

<ToolbarCustomDemo />

## Callbacks

React to editor events — document changes, saves, selection updates, clipboard actions, and more.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onChange` | `(document: Document) => void` | — | Callback when document changes |
| `onSave` | `(buffer: ArrayBuffer) => void` | — | Callback when document is saved |
| `onSelectionChange` | `(state: SelectionState \| null) => void` | — | Callback when selection changes |
| `onError` | `(error: Error) => void` | — | Callback on error |
| `onFontsLoaded` | `() => void` | — | Callback when fonts are loaded |
| `onPrint` | `() => void` | — | Callback when print is triggered |
| `onCopy` | `() => void` | — | Callback when content is copied |
| `onCut` | `() => void` | — | Callback when content is cut |
| `onPaste` | `() => void` | — | Callback when content is pasted |

```tsx
<DocxEditor
  documentBuffer={buf}
  onSave={(buffer) => uploadToServer(buffer)}
  onChange={(doc) => setDirty(true)}
  onError={(err) => toast.error(err.message)}
/>
```

## Styling

Apply a custom theme, add CSS classes, or pass inline styles to the editor container.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `Theme \| null` | — | Theme for styling |
| `className` | `string` | — | Additional CSS class name |
| `style` | `CSSProperties` | — | Additional inline styles |
| `placeholder` | `ReactNode` | — | Placeholder when no document |
| `loadingIndicator` | `ReactNode` | — | Loading indicator |
| `printOptions` | `PrintOptions` | — | Print options for print preview |

```tsx
<DocxEditor
  documentBuffer={buf}
  className="rounded-lg"
  placeholder={<EmptyState />}
  loadingIndicator={<Spinner />}
/>
```

## Other Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `fontFamilies` | `ReadonlyArray<string \| FontOption>` | — | Custom list of fonts shown in the toolbar's font-family dropdown. Strings render in the "Other" group; pass `FontOption[]` for category grouping and CSS fallback chains. Omit to use the built-in 12-font default. An empty array renders an empty (but enabled) dropdown. Pass a stable reference (memoized or module-level) — inline arrays create a new identity per render and invalidate the picker's memo. |
| `i18n` | `Translations` | — | Translation overrides. Import a locale JSON file and pass it directly. |

## Ref Methods

Access imperative methods via a ref. These let you programmatically save, zoom, navigate, and print.

| Method | Signature | Description |
| --- | --- | --- |
| `getAgent` | `() => DocumentAgent \| null` | Get the DocumentAgent for programmatic access |
| `getDocument` | `() => Document \| null` | Get the current document |
| `getEditorRef` | `() => PagedEditorRef \| null` | Get the editor ref |
| `save` | `(options?: { selective?: boolean }) => Promise<ArrayBuffer \| null>` | Save the document to buffer. Pass \{ selective: false \} to force full repack. |
| `setZoom` | `(zoom: number) => void` | Set zoom level |
| `getZoom` | `() => number` | Get current zoom level |
| `focus` | `() => void` | Focus the editor |
| `getCurrentPage` | `() => number` | Get current page number |
| `getTotalPages` | `() => number` | Get total page count |
| `scrollToPage` | `(pageNumber: number) => void` | Scroll the paginated view so the given page is in view. Page numbers are 1-indexed (matches `getCurrentPage` / `getTotalPages`). No-op for out-of-range or non-integer values. |
| `scrollToParaId` | `(paraId: string) => boolean` | Scroll the paginated view to the paragraph with the given Word `w14:paraId`. |
| `scrollToPosition` | `(pmPos: number) => void` | Scroll the paginated view to a specific ProseMirror document position. Use this when you have a raw PM offset; for Word `w14:paraId` use `scrollToParaId` instead. |
| `openPrintPreview` | `() => void` | Open print preview |
| `print` | `() => void` | Print the document directly |
| `loadDocument` | `(doc: Document) => void` | Load a pre-parsed document programmatically |
| `loadDocumentBuffer` | `(buffer: DocxInput) => Promise<void>` | Load a DOCX buffer programmatically (ArrayBuffer, Uint8Array, Blob, or File) |

```tsx
const ref = useRef<DocxEditorRef>(null);

// Save and upload
const buffer = await ref.current.save();
await fetch('/api/upload', { method: 'POST', body: buffer });

// Navigation & zoom
ref.current.setZoom(1.5);
ref.current.scrollToPage(3);

// Get document model
const doc = ref.current.getDocument();
console.log(doc.body.sections.length);

// Print
ref.current.print();
```

---

# Realtime Collaboration

Source: https://www.docx-editor.dev/docs/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 [online editor](/editor), click **Collaborate**, share the URL with a tab/colleague.

## 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-js-editor';
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-js-editor';

// 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/provider) | 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.

---

# Toolbar Customization

Source: https://www.docx-editor.dev/docs/toolbar

## Overview

The editor uses a two-level composable toolbar with a title bar and a formatting bar.

### Layout Structure

<ToolbarLayoutDiagram />

- **Title Bar**: 3-column layout — Logo and Right Actions span full height, Document Name + Menus stack vertically in the center
- **Formatting Bar**: Rendered inside a rounded pill with a subtle gray background
- Every slot is customizable — pass your own logo, action buttons, or extra toolbar items

There are **two ways** to customize the toolbar:

1. **DocxEditor props** — Quick setup with render props
2. **Compound components** — Full control using `EditorToolbar` and its sub-components

---

## Quick Setup (DocxEditor Props)

The simplest way to customize the toolbar:

```tsx
import { DocxEditor } from '@eigenpal/docx-js-editor';

function App() {
  const [fileName, setFileName] = useState('Untitled.docx');

  return (
    <DocxEditor
      documentBuffer={buffer}
      renderLogo={() => <img src="/logo.svg" alt="Logo" />}
      documentName={fileName}
      onDocumentNameChange={setFileName}
      renderTitleBarRight={() => (
        <div>
          <button onClick={handleSave}>Save</button>
        </div>
      )}
    />
  );
}
```

### DocxEditor Toolbar Props

| Prop                   | Type                     | Default | Description                                       |
| ---------------------- | ------------------------ | ------- | ------------------------------------------------- |
| `renderLogo`           | `() => ReactNode`        | —       | Custom logo/icon in the title bar                 |
| `documentName`         | `string`                 | —       | Editable document name displayed in the title bar |
| `onDocumentNameChange` | `(name: string) => void` | —       | Called when the user edits the document name      |
| `renderTitleBarRight`  | `() => ReactNode`        | —       | Custom actions on the right side of the title bar |

All existing toolbar props (`showToolbar`, `showZoomControl`, `showRuler`, `toolbarExtra`, etc.) continue to work.

---

## Customizing the Font Dropdown

The toolbar's font-family dropdown can be customized via the `fontFamilies` prop on `DocxEditor`. Pass either bare strings, full `FontOption` objects, or a mix. Omit the prop to keep the built-in 12-font default.

### Bare strings

Strings render in the "Other" group:

```tsx
import { DocxEditor } from '@eigenpal/docx-js-editor';

<DocxEditor
  documentBuffer={buffer}
  fontFamilies={['Arial', 'Helvetica', 'Comic Sans MS']}
/>
```

### `FontOption` objects (CSS fallbacks + grouping)

Use `FontOption[]` to enable CSS fallback chains and category grouping (`sans-serif` / `serif` / `monospace` / `other`):

```tsx
import { DocxEditor, type FontOption } from '@eigenpal/docx-js-editor';

const FONTS: FontOption[] = [
  { name: 'Inter', fontFamily: 'Inter, system-ui, sans-serif', category: 'sans-serif' },
  { name: 'Roboto', fontFamily: 'Roboto, sans-serif', category: 'sans-serif' },
  { name: 'Source Serif', fontFamily: '"Source Serif Pro", Georgia, serif', category: 'serif' },
  { name: 'JetBrains Mono', fontFamily: '"JetBrains Mono", monospace', category: 'monospace' },
];

<DocxEditor documentBuffer={buffer} fontFamilies={FONTS} />
```

### Mixed input

Strings and `FontOption` objects can be combined; strings still land in "Other":

```tsx
<DocxEditor
  documentBuffer={buffer}
  fontFamilies={[
    { name: 'Inter', fontFamily: 'Inter, sans-serif', category: 'sans-serif' },
    'Comic Sans MS',
  ]}
/>
```

> **Stable reference required.** Pass a memoized array or hoist it to module scope. An inline `fontFamilies={[...]}` creates a fresh identity on every render and invalidates the picker's internal memo.

An empty array (`fontFamilies={[]}`) renders an empty but still-enabled dropdown.

---

## Compound Component API

For full control over the toolbar structure, use `EditorToolbar` directly:

```tsx
import { EditorToolbar, type EditorToolbarProps } from '@eigenpal/docx-js-editor';

function MyEditor({ toolbarProps }: { toolbarProps: EditorToolbarProps }) {
  return (
    <EditorToolbar {...toolbarProps}>
      <EditorToolbar.TitleBar>
        <EditorToolbar.Logo>
          <img src="/logo.svg" alt="My App" />
        </EditorToolbar.Logo>
        <EditorToolbar.DocumentName
          value={fileName}
          onChange={setFileName}
          placeholder="Untitled"
        />
        <EditorToolbar.MenuBar />
        <EditorToolbar.TitleBarRight>
          <button onClick={handleSave}>Save</button>
          <button onClick={handleShare}>Share</button>
        </EditorToolbar.TitleBarRight>
      </EditorToolbar.TitleBar>
      <EditorToolbar.FormattingBar />
    </EditorToolbar>
  );
}
```

### Sub-Components

#### `EditorToolbar`

The root wrapper. Provides toolbar context to all sub-components.

| Prop              | Type        | Description                                                   |
| ----------------- | ----------- | ------------------------------------------------------------- |
| `children`        | `ReactNode` | Sub-components (TitleBar, FormattingBar)                      |
| `className`       | `string`    | Additional CSS class for the container                        |
| _...ToolbarProps_ |             | All standard toolbar props (formatting state, handlers, etc.) |

#### `EditorToolbar.TitleBar`

Three-column layout. Automatically arranges children:

- **Left column**: Logo (spans full height)
- **Center column**: DocumentName on top, MenuBar below
- **Right column**: TitleBarRight (spans full height)

| Prop       | Type        | Description                                |
| ---------- | ----------- | ------------------------------------------ |
| `children` | `ReactNode` | Logo, DocumentName, MenuBar, TitleBarRight |

#### `EditorToolbar.Logo`

Renders custom content (icon, image, badge) left-aligned in the title bar.

| Prop       | Type        | Description  |
| ---------- | ----------- | ------------ |
| `children` | `ReactNode` | Logo content |

#### `EditorToolbar.DocumentName`

Editable text input styled as a borderless field.

| Prop          | Type                      | Default      | Description           |
| ------------- | ------------------------- | ------------ | --------------------- |
| `value`       | `string`                  | —            | Current document name |
| `onChange`    | `(value: string) => void` | —            | Called on name change |
| `placeholder` | `string`                  | `'Untitled'` | Placeholder text      |

#### `EditorToolbar.MenuBar`

Renders File, Format, and Insert dropdown menus. Automatically wired to the toolbar context — no props needed.

Menu contents are derived from the toolbar context (print, page setup, text direction, image/table insert, page break, table of contents).

#### `EditorToolbar.TitleBarRight`

Right-aligned container for custom actions (buttons, toggles, status indicators).

| Prop       | Type        | Description                   |
| ---------- | ----------- | ----------------------------- |
| `children` | `ReactNode` | Action buttons, toggles, etc. |

#### `EditorToolbar.FormattingBar`

The icon formatting toolbar (undo/redo, zoom, fonts, bold/italic/underline, colors, alignment, lists, etc.) rendered inside a rounded pill with a subtle gray background. Can also be used standalone outside of `EditorToolbar`.

| Prop       | Type        | Description                                                             |
| ---------- | ----------- | ----------------------------------------------------------------------- |
| `children` | `ReactNode` | Additional toolbar items appended at the end                            |
| `inline`   | `boolean`   | When true, renders with `display: contents` for embedding in a flex row |

---

## Customization Patterns

### Custom logo with branding

```tsx
<DocxEditor
  renderLogo={() => (
    <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
      <img src="/logo.svg" width={24} height={24} />
      <span style={{ fontWeight: 600 }}>My App</span>
    </div>
  )}
/>
```

### Right-side actions with status

```tsx
<DocxEditor
  renderTitleBarRight={() => (
    <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
      <span style={{ fontSize: 12, color: '#666' }}>Saved</span>
      <button onClick={handleExport}>Export</button>
      <button onClick={handleShare}>Share</button>
    </div>
  )}
/>
```

### Extra formatting toolbar items

Use `toolbarExtra` to append custom buttons to the formatting bar:

```tsx
<DocxEditor
  toolbarExtra={
    <>
      <button onClick={handleSpellCheck}>Spell Check</button>
      <button onClick={handleWordCount}>Word Count</button>
    </>
  }
/>
```

### Compound components with custom elements

Mix standard sub-components with your own elements inside the TitleBar:

```tsx
<EditorToolbar {...toolbarProps}>
  <EditorToolbar.TitleBar>
    <EditorToolbar.Logo>
      <MyBrandLogo />
    </EditorToolbar.Logo>
    <EditorToolbar.DocumentName value={name} onChange={setName} />
    <EditorToolbar.MenuBar />
    <EditorToolbar.TitleBarRight>
      <UserAvatar />
      <ShareButton />
      <SaveButton />
    </EditorToolbar.TitleBarRight>
  </EditorToolbar.TitleBar>
  <EditorToolbar.FormattingBar>
    <CustomToolbarButton icon="spell_check" onClick={handleSpellCheck} />
  </EditorToolbar.FormattingBar>
</EditorToolbar>
```

---

# Translations (i18n)

Source: https://www.docx-editor.dev/docs/translations

## Overview

`@eigenpal/docx-js-editor` ships with built-in internationalization that supports **any language**. Every toolbar label, tooltip, context menu item, dialog, and UI string can be translated.

All locale files live in `packages/react/i18n/` as JSON. English (`en.json`) is the source of truth — community-contributed locales mirror its structure and use `null` for untranslated keys (which fall back to English automatically).

Community contributions for new locales are welcome — see [Contributing a new locale](#contributing-a-new-locale) below.

## Quick start

Import a locale JSON file and pass it via the `i18n` prop:

```tsx
import { DocxEditor } from "@eigenpal/docx-js-editor";
import de from "@eigenpal/docx-js-editor/i18n/de.json";
import "@eigenpal/docx-js-editor/styles.css";

function App() {
  return (
    <DocxEditor
      documentBuffer={buffer}
      i18n={de}
      showToolbar
    />
  );
}
```

That's it — all toolbar buttons, tooltips, dialogs, and status messages now appear in German.

## Available locales

| Code | Language | Import path |
|------|----------|-------------|
| `en` | English (default) | Built-in, no import needed |
| `pl` | Polish (Polski) | `@eigenpal/docx-js-editor/i18n/pl.json` |
| `de` | German (Deutsch) | `@eigenpal/docx-js-editor/i18n/de.json` |

## Dynamic locale switching

Wrap the locale import in state to let users choose their language at runtime:

```tsx
import { useState } from "react";
import { DocxEditor } from "@eigenpal/docx-js-editor";
import pl from "@eigenpal/docx-js-editor/i18n/pl.json";
import de from "@eigenpal/docx-js-editor/i18n/de.json";
import "@eigenpal/docx-js-editor/styles.css";

const locales = {
  en: undefined, // built-in default
  pl,
  de,
};

function App() {
  const [lang, setLang] = useState<"en" | "pl" | "de">("en");

  return (
    <>
      <select value={lang} onChange={(e) => setLang(e.target.value as "en" | "pl" | "de")}>
        <option value="en">English</option>
        <option value="pl">Polski</option>
        <option value="de">Deutsch</option>
      </select>

      <DocxEditor
        documentBuffer={buffer}
        i18n={locales[lang]}
        showToolbar
      />
    </>
  );
}
```

Only the imported locale gets bundled — tree-shaking keeps your bundle lean.

## Key states in locale files

Every key in a community locale file can be in one of three states:

| State | Value | Behavior |
|-------|-------|----------|
| **Translated** | `"Pogrubienie"` | Displayed to user |
| **Not yet translated** | `null` | Falls back to English |
| **Missing** | _(key absent)_ | **CI fails** — must be added as `null` |

Setting a key to `null` means "this key exists but hasn't been translated yet." The editor shows the English string as a fallback, and translators can find untranslated strings by searching for `null`:

```json
{
  "toolbar": {
    "bold": "Pogrubienie",
    "italic": null,
    "underline": null
  }
}
```

Here, "Bold" shows as "Pogrubienie", while "Italic" and "Underline" display in English until translated.

## Interpolation and pluralization

### Interpolation

Insert dynamic values with `{variable}` placeholders:

```json
"greeting": "Hello {name}!"
```

### Cardinal pluralization

The system uses ICU MessageFormat syntax for plural forms:

```json
"followers": "You have {count, plural, =0 {no followers yet} =1 {one follower} other {# followers}}."
```

- `=0`, `=1`, `=2` — exact matches (checked first)
- `one`, `few`, `many`, `other` — CLDR plural categories (language-dependent)
- `#` — replaced with the actual number

Each locale file includes a `_lang` field that tells `Intl.PluralRules` which rules to apply. Polish, for example, has `one`/`few`/`many`/`other`:

```json
"followers": "{count, plural, =0 {brak obserwujących} one {# obserwujący} few {# obserwujących} many {# obserwujących} other {# obserwujących}}"
```

## Contributing a new locale

Want to add a new language to the editor? The project includes CLI tools that make it straightforward.

### 1. Scaffold a new locale

```bash
bun run i18n:new de        # German
bun run i18n:new pt-BR     # Brazilian Portuguese
bun run i18n:new zh-Hans   # Simplified Chinese
```

This creates `packages/react/i18n/<lang>.json` with all keys set to `null`, mirroring the structure of `en.json`. Use a [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) language tag.

### 2. Translate strings

Open the generated file and replace `null` values with translations. You don't need to translate everything at once — partial translations are welcome. Untranslated keys (`null`) fall back to English.

**Tips:**

- Keep `{variable}` placeholders as-is — they get replaced at runtime
- Keyboard shortcuts (Ctrl+B, Ctrl+Z) should keep the key part unchanged
- Font names (Arial, Calibri) and typography terms (Sans Serif, Monospace) are typically not translated
- Page size identifiers (Letter, A4) keep the standard name

### 3. Check your progress

```bash
bun run i18n:status
```

```
Source: en.json (483 keys)

Locale      Translated  Untranslated  Coverage
----------------------------------------------
de          210         273           43% ████████░░░░░░░░░░░░
```

### 4. Validate

```bash
bun run i18n:validate    # check all locale files are in sync
bun run i18n:fix         # auto-repair if needed
```

### 5. Open a PR

Include your coverage in the PR description (e.g., "German: 100% translated" or "Japanese: toolbar + dialogs translated, errors section still null").

See the full contribution guide at [docs/i18n.md on GitHub](https://github.com/eigenpal/docx-editor/blob/main/docs/i18n.md).

## Adding new English strings (for contributors)

When adding a new feature with user-facing text:

1. **Add to `en.json`** — nest by feature area:

```json
{
  "dialogs": {
    "myNewDialog": {
      "title": "My Dialog",
      "description": "Some description"
    }
  }
}
```

2. **Use in component** with the `useTranslation()` hook:

```tsx
const { t } = useTranslation();
<h2>{t('dialogs.myNewDialog.title')}</h2>
```

Types update automatically — `t()` will autocomplete your new key.

3. **Sync locale files**:

```bash
bun run i18n:fix
```

This adds your new keys as `null` in all community locale files. CI will fail if you skip this step.

### Key naming conventions

- Nest by feature area: `toolbar.*`, `dialogs.findReplace.*`, `comments.*`
- Use camelCase for keys: `matchCount`, `insertRowAbove`
- Shared strings go in `common.*`: Cancel, Insert, Apply, Close, Delete
- Don't duplicate — if a string exists in `common.*`, use it

## CLI reference

| Command | Description |
|---------|-------------|
| `bun run i18n:new <lang>` | Scaffold a new locale file with all keys set to `null` |
| `bun run i18n:status` | Show translation coverage for all locales |
| `bun run i18n:validate` | Check all locale files are in sync with `en.json` |
| `bun run i18n:fix` | Auto-repair: add missing keys as `null`, remove extras |

## Architecture

```
packages/react/i18n/en.json            → Source of truth (all strings)
packages/react/src/i18n/types.ts       → Auto-derived types from en.json
packages/react/src/i18n/LocaleContext.tsx → React Context + useTranslation hook
packages/react/src/i18n/index.ts       → Barrel exports
scripts/validate-i18n.mjs             → CI/pre-commit validation
```

- **Zero runtime dependencies** — uses React Context only
- **Type-safe** — `t()` accepts only valid dot-notation keys, autocomplete works
- **Tree-shakeable** — only the imported locale gets bundled
- **Null = untranslated** — deep merge skips nulls, falls back to English

## Limitations

- **No RTL layout** — string translation works, but the editor UI layout is not RTL-ready. RTL support is a separate effort.

## Next steps

- [Polish translation blog post](/blog/polish-translation-docx-editor) — deep dive into the Polish locale
- [German translation blog post](/blog/german-translation-docx-editor) — deep dive into the German locale
- [Full i18n contribution guide on GitHub](https://github.com/eigenpal/docx-editor/blob/main/docs/i18n.md) — upstream source of truth
- [Props Reference](/docs/props) — full list of configuration props
- [Toolbar Customization](/docs/toolbar) — customize toolbar layout and actions

---