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

PropTypeDescription
documentDocumentSourceUint8Array, 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.
authorstringAuthor for later comments, replies, and tracked changes. Updates without a rebuild; existing revisions keep their authors.
localestringBCP 47 locale for regional date input and generated labels, Defaults to en-US. Updates without a rebuild.
zoomnumberNumeric display scale. Updates without a rebuild.
zoomModeZoomMode | '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.
contentLockPolicyContentLockPolicy{ 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.
modulesreadonly EditorModule[]Capability modules from @docx-editor.dev/pro/vue, such as reviewModule().

Fonts

PropTypeDescription
fontsFontConfiguration | FontConfigurationFragment | FontResolverFont 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

PropTypeDescription
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

PropTypeDescription
chromebooleanShows the packaged frame. Set false for the document surface only.
titlestringTitle-bar document name.
menuboolean | DocxEditorMenuPropsToggles or configures the menu bar.
navigationboolean | DocxEditorNavigationPropsToggles or configures the navigation pane.
rulersbooleanShows or hides both rulers.
hyperlinkPopupbooleanShows or hides the hyperlink popover.
contextMenuboolean | DocxEditorContextMenuPropsToggles or configures the context menu.
popupsDocxEditorPopupsReplaces automatic popups with definePopup(MyPopup) or render callbacks. See Customize popups.
openFailureboolean | DocxEditorOpenFailurePropsConfigures the dialog for a file that does not open. See open failures.
t(key, params?) => stringResolves live chrome and drawing labels.
i18nTranslationsLive chrome and drawing labels for this editor. See i18n.

Handle events and slots

<DocxEditor> emits seven events:

EventPayloadDescription
@readyeditor: EditorThe editor and content mount are ready.
@changechange: DocumentChangeA mutation completed. The payload has revision and identity changes, not bytes.
@savenoneThe packaged Save action ran. Read bytes through the ref.
@opennoneThe packaged Open action ran.
@title-changetitle: stringThe title changed. Listening enables title editing.
@font-errorerror: EditorFontErrorFont resolution failed.
@revision-markup-changesettings: ResolvedRevisionMarkupThe API or the markup dialog proposed new revision markup settings. Store them in revisionMarkup to accept them.
SlotPropsDescription
#titleBarLeftnoneHost content before the title.
#titleBarRightnoneHost content after the title.
#loadingIndicatornoneReplaces 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();
MethodReturnsDescription
save()Promise<ArrayBuffer | null>Serializes the document to .docx. Returns null when no document is loaded.
load(document)voidLoads DOCX bytes, 'blank', or a DocumentHandle.
getDocumentHandle()DocumentHandle | nullReturns the current document's revision and its loadId, which changes on every load.
getEditor()Editor | nullReturns the full editor facade.
exec(command, options?)ExecResultRuns a typed command with packaged-chrome validation; see EditorExecOptions.
snapshot(options?)EditorSnapshotReads state synchronously from an optional scope.
focus()voidFocuses the document surface.

Limits

  • fieldResults, contentLockPolicy, lockedControlNavigation, and modules apply at creation. To change them, remount with a different :key.
  • Collaboration refuses fieldResults="editable" with a TypeError.
  • The drawing renderers from drawingModule() and reviewModule() serve every editor in the page. A remount does not remove them. See Advanced drawing rendering.
  • DocxEditorRoot emits only ready, change, font-error, and revision-markup-change. File and title events belong to <DocxEditor>.
  • If you hide hyperlinkPopup, mount a panel that calls useHyperlinkPopup(), or the Insert link controls stay disabled.
  • To customize unsupported content, register DocxEditor.UnsupportedElement components. See custom unsupported-content components.

Next steps