Props
Reference for Vue document props, chrome, events, slots, and the seven ref methods.
Configure the editor
This example loads DOCX bytes, sets an author, and handles the save event:
<script setup lang="ts">
import { ref } from 'vue';
import { DocxEditor, type DocxEditorRef } from '@docx-editor.dev/vue';
const props = defineProps<{
bytes: Uint8Array;
upload: (buffer: ArrayBuffer) => Promise<void>;
}>();
const editorRef = ref<DocxEditorRef | null>(null);
async function onSave() {
const buffer = await editorRef.value?.save();
if (buffer) await props.upload(buffer);
}
</script>
<template>
<DocxEditor ref="editorRef" :document="bytes" mode="edit" author="Jess Lin" @save="onSave" />
</template>For generated signatures, see the Vue API reference.
Set props
Document
| Prop | Type | Description |
|---|---|---|
document | DocumentSource | Uint8Array, ArrayBuffer, 'blank', or a DocumentHandle. A new identity rebuilds the editor. Resolve URLs with useDocxSource(). |
mode | 'edit' | 'view' | 'suggesting' | Editing mode. Defaults to 'edit'. Updates without a rebuild. |
author | string | Author for later comments, replies, and tracked changes. Updates without a rebuild; existing revisions keep their authors. |
locale | string | BCP 47 locale for regional date input and generated labels, Defaults to en-US. Updates without a rebuild. |
zoom | number | Numeric display scale. Updates without a rebuild. |
zoomMode | ZoomMode | 'auto' | Zoom source. 'auto' fits the page width. |
fieldResults | 'atomic' | 'editable' | 'editable' allows editing saved field results. Defaults to 'atomic'. See Edit saved field results. |
contentLockPolicy | ContentLockPolicy | { allowFormattingInLockedContent: true } allows formatting in content-locked controls. See Formatting content-locked controls. |
lockedControlNavigation | 'characters' | 'atomic' | Caret movement through a locked inline control: per character (default) or as one unit. See Caret movement. |
modules | readonly EditorModule[] | Capability modules from @docx-editor.dev/pro/vue, such as reviewModule(). |
Fonts
| Prop | Type | Description |
|---|---|---|
fonts | FontConfiguration | FontConfigurationFragment | FontResolver | Font bytes or an on-demand resolver for text shaping and pagination. |
Wrap resolvers such as packagedFonts() in useFonts() to keep one identity. For loading choices, see Fonts and measurement.
Dark mode
| Prop | Type | Description |
|---|---|---|
colorMode | 'light' | 'dark' | 'system' | Sets the chrome theme and a display transform on the canvas. Defaults to 'light'. |
colorMode does not change authored colors, saved output, or printing. See Dark mode.
Chrome and layout
| Prop | Type | Description |
|---|---|---|
chrome | boolean | Shows the packaged frame. Set false for the document surface only. |
title | string | Title-bar document name. |
menu | boolean | DocxEditorMenuProps | Toggles or configures the menu bar. |
navigation | boolean | DocxEditorNavigationProps | Toggles or configures the navigation pane. |
rulers | boolean | Shows or hides both rulers. |
hyperlinkPopup | boolean | Shows or hides the hyperlink popover. |
contextMenu | boolean | DocxEditorContextMenuProps | Toggles or configures the context menu. |
popups | DocxEditorPopups | Replaces automatic popups with definePopup(MyPopup) or render callbacks. See Customize popups. |
openFailure | boolean | DocxEditorOpenFailureProps | Configures the dialog for a file that does not open. See open failures. |
t | (key, params?) => string | Resolves live chrome and drawing labels. |
i18n | Translations | Live chrome and drawing labels for this editor. See i18n. |
Handle events and slots
<DocxEditor> emits seven events:
| Event | Payload | Description |
|---|---|---|
@ready | editor: Editor | The editor and content mount are ready. |
@change | change: DocumentChange | A mutation completed. The payload has revision and identity changes, not bytes. |
@save | none | The packaged Save action ran. Read bytes through the ref. |
@open | none | The packaged Open action ran. |
@title-change | title: string | The title changed. Listening enables title editing. |
@font-error | error: EditorFontError | Font resolution failed. |
@revision-markup-change | settings: ResolvedRevisionMarkup | The API or the markup dialog proposed new revision markup settings. Store them in revisionMarkup to accept them. |
| Slot | Props | Description |
|---|---|---|
#titleBarLeft | none | Host content before the title. |
#titleBarRight | none | Host content after the title. |
#loadingIndicator | none | Replaces the loading spinner. See loading indicator. |
#openFailureActions | { failure, message, dismiss } | Adds buttons to the dialog for a file that does not open. See open failures. |
Use the ref
Capture DocxEditorRef with a template ref:
const buffer = await editorRef.value?.save();
const editor = editorRef.value?.getEditor();
editorRef.value?.focus();| Method | Returns | Description |
|---|---|---|
save() | Promise<ArrayBuffer | null> | Serializes the document to .docx. Returns null when no document is loaded. |
load(document) | void | Loads DOCX bytes, 'blank', or a DocumentHandle. |
getDocumentHandle() | DocumentHandle | null | Returns the current document's revision and its loadId, which changes on every load. |
getEditor() | Editor | null | Returns the full editor facade. |
exec(command, options?) | ExecResult | Runs a typed command with packaged-chrome validation; see EditorExecOptions. |
snapshot(options?) | EditorSnapshot | Reads state synchronously from an optional scope. |
focus() | void | Focuses the document surface. |
Limits
fieldResults,contentLockPolicy,lockedControlNavigation, andmodulesapply at creation. To change them, remount with a different:key.- Collaboration refuses
fieldResults="editable"with aTypeError. - The drawing renderers from
drawingModule()andreviewModule()serve every editor in the page. A remount does not remove them. See Advanced drawing rendering. DocxEditorRootemits onlyready,change,font-error, andrevision-markup-change. File and title events belong to<DocxEditor>.- If you hide
hyperlinkPopup, mount a panel that callsuseHyperlinkPopup(), or the Insert link controls stay disabled. - To customize unsupported content, register
DocxEditor.UnsupportedElementcomponents. See custom unsupported-content components.
Next steps
- Vue examples: Automate an open editor.
- Vue composition: Build your own chrome.
- Vue API reference: Generated signatures.