# Props

Source: https://docx-editor.portone.io/docs/props

Every DocxEditor prop, the imperative handle, and which props are read once.

`DocxEditor` is the single component the React entry exports.

## Props [#props]

| Prop                | Type                                    | Default                  | What it does                                                                                                                                                                                 |
| ------------------- | --------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `document`          | `ArrayBuffer \| Uint8Array \| Blob`     | required                 | The document to open. Bytes open immediately; a `Blob` or `File` is read first. The document that arrived last is the one opened.                                                            |
| `mode`              | `DocxEditorMode`                        | required                 | What the editor is for, and whose comments it writes. See [Mode](#mode).                                                                                                                     |
| `renderImportError` | `(error: DocxImportError) => ReactNode` | built-in panel           | What to render in place of the editor when the document was refused.                                                                                                                         |
| `showPageGuides`    | `boolean`                               | `true`                   | Whether to draw approximate page boundaries, in every mode.                                                                                                                                  |
| `zoom`              | `DocxEditorZoom`                        | uncontrolled             | The visual scale, when the host owns it.                                                                                                                                                     |
| `defaultZoom`       | `DocxEditorZoom`                        | `"fit-width"`            | The initial scale when the editor owns it.                                                                                                                                                   |
| `onZoomChange`      | `(zoom: DocxEditorZoom) => void`        | -                        | Receives toolbar requests. A controlled host must update `zoom` for one to take effect.                                                                                                      |
| `fontFallbacks`     | `FontFallbacks`                         | `DEFAULT_FONT_FALLBACKS` | The fonts drawn in place of names missing from the reader's machine. See [Styling](https://docx-editor.portone.io/docs/styling.md#font-fallbacks).                                                                            |
| `presets`           | `DocxEditorPresets`                     | package defaults         | The lists the built-in pickers offer. See [Presets](https://docx-editor.portone.io/docs/editor-api/plugins-and-presets.md#presets).                                                                                           |
| `plugins`           | `readonly Plugin[]`                     | -                        | ProseMirror plugins placed ahead of the built-in ones.                                                                                                                                       |
| `contextMenus`      | `boolean`                               | `true`                   | Whether the right click opens the editor's own menus; `false` leaves it to the browser.                                                                                                      |
| `className`         | `string`                                | -                        | Added to the editor's outer frame.                                                                                                                                                           |
| `style`             | `CSSProperties`                         | -                        | Applied to that frame.                                                                                                                                                                       |
| `onReady`           | `(view: EditorView) => void`            | -                        | Called with the view once a document is mounted.                                                                                                                                             |
| `onChange`          | `() => void`                            | -                        | Called on every state change, cursor and selection moves included.                                                                                                                           |
| `onEditRefused`     | `(refusal: EditRefusal) => void`        | -                        | Called when the editor turns down an edit in the document body, such as typing into locked content. See [When an edit is refused](https://docx-editor.portone.io/docs/editor-api/modes-and-locks.md#when-an-edit-is-refused). |

`DocxEditorProps`, `DocxEditorMode`, `DocxEditorZoom`, `DocxEditorPresets`, `CommentAuthor`,
`EditableComments`, `DocxSource`, `EditRefusal`, and the types it is made of are exported from the
root entry.

## Mode [#mode]

```ts
type DocxEditorMode =
  | { kind: "readOnly" }
  | {
      kind: "comment";
      author: CommentAuthor;
      editableComments?: EditableComments;
    }
  | {
      kind: "edit";
      author: CommentAuthor;
      editableComments?: EditableComments;
      toolbar?: boolean;
      locking?: boolean;
    };

interface CommentAuthor {
  id: string;
  name: string;
  initials?: string;
}

type EditableComments = "own" | "all";
```

[Modes](https://docx-editor.portone.io/docs/features/modes.md) describes what each kind lets a reader do, and
[Modes and locks](https://docx-editor.portone.io/docs/editor-api/modes-and-locks.md) how a control of your own reads it.

`author` is the identity the built-in composers write: `id` is an opaque string of your choosing,
such as your user id, recorded in the document beside `name`; `initials` is optional.
Give each `id` a distinct `name` within the document. A reused name resolves to no identity, so the
default `editableComments: "own"` leaves those comments editable by everyone, and a file written
under a name another identity already holds is refused by
[server verification](https://docx-editor.portone.io/docs/core/verifying-a-commenters-file.md) as `comment-author-forged`.

`editableComments` is whose comments the panel offers to edit or delete: `"own"` (the default) is
a comment carrying this `id` or no identity, `"all"` is every comment.
`toolbar` defaults to `true`; `locking` defaults to `false` and adds the controls for locking part
of a document.

The kind, `author`, and `editableComments` may change on an open document; the editor switches in
place and keeps the view, its history, and the plugins.

## The handle [#the-handle]

```ts
interface DocxEditorHandle {
  view: EditorView;
  exportBytes: () => Uint8Array;
  exportProblems: () => readonly ExportProblem[];
}
```

The ref holds `null` until a document has been opened, and again for a refused document, so read
it at click time.
`exportBytes` throws `DocxExportError` when it cannot write safely; `exportProblems` reports every
reason it would, each under the same code and with the `reason` and `pos` naming the content to put
back ([Checking before export](https://docx-editor.portone.io/docs/core/errors.md#checking-before-export)).
A thrown `DocxExportError` carries the entry it was raised for as `problem`.
[Getting started](https://docx-editor.portone.io/docs/getting-started.md#export-the-edited-document) covers `downloadDocx`, which
wraps the handle for a browser download.

## Props read once [#props-read-once]

`plugins`, `fontFallbacks`, `defaultZoom`, and `contextMenus` are read when the editor mounts;
later changes are ignored, so building them inline is harmless.
To change one, or to swap the document, change the component's `key` and let it remount.
Every other prop, `mode` included, takes effect on the render that changes it.