Composition

Build a custom Vue DOCX editor from primitives, compound parts, and composables.

<DocxEditor> is a packaged arrangement of public components. Compose those components yourself when you need a different layout or your own controls.

Compose an editor

This example mounts a toolbar and the document in a bounded flex column:

<script setup lang="ts">
import {
  DocxEditorContent,
  DocxEditorContextMenu,
  DocxEditorHyperLink,
  DocxEditorRoot,
  DocxEditorToolbar,
  DocxEditorViewport,
} from '@docx-editor.dev/vue';
import '@docx-editor.dev/vue/styles.css';

defineProps<{ bytes: Uint8Array }>();
</script>

<template>
  <div class="docx-editor" style="display: flex; flex-direction: column; height: 100vh">
    <DocxEditorRoot :document="bytes">
      <DocxEditorToolbar />
      <DocxEditorViewport style="flex: 1; min-height: 0">
        <DocxEditorContent />
        <DocxEditorHyperLink />
        <DocxEditorContextMenu />
      </DocxEditorViewport>
    </DocxEditorRoot>
  </div>
</template>
RequirementWhy
DocxEditorRootOwns the editor instance. It renders no DOM element, so its children sit in your flex column.
DocxEditorViewportSupplies the scroll container. DocxEditorContent must be inside it.
DocxEditorContentMounts the painted, editable pages.
Editor stylesheetStyles the viewport and packaged parts. Import it once.
Bounded heightGives the viewport room. Use flex: 1 and min-height: 0 on the viewport and on any element between it and the container.
.docx-editor wrapperMakes editor styles and --doc-* tokens available to your own controls.

If you use Pro review chrome, register its modules once on DocxEditorRoot. For setup, see the Pro package documentation.

UI language and date input

DocxEditorRoot reads UI strings from LocaleProvider and has no i18n prop. Set locale separately for regional date input:

<script setup lang="ts">
import { defineComponent, h } from 'vue';
import {
  DocxEditorContent,
  DocxEditorRoot,
  DocxEditorToolbar,
  DocxEditorViewport,
  LocaleProvider,
  useChromeTranslate,
} from '@docx-editor.dev/vue';
import { pl } from '@docx-editor.dev/i18n';

defineProps<{ bytes: Uint8Array }>();
const LocalizedToolbar = defineComponent({
  setup() {
    const t = useChromeTranslate();
    return () => h(DocxEditorToolbar, { t: t.value });
  },
});
</script>

<template>
  <LocaleProvider :i18n="pl">
    <DocxEditorRoot :document="bytes" locale="pl-PL">
      <LocalizedToolbar />
      <DocxEditorViewport>
        <DocxEditorContent />
      </DocxEditorViewport>
    </DocxEditorRoot>
  </LocaleProvider>
</template>

Pass a Map to useChromeTranslate(overrides) to rename labels. For catalogs, see Internationalization.

Reach the editor from a parent

Components inside the root call useDocxEditor(). A parent layout that holds the editor calls provideDocxEditor():

<script setup lang="ts">
import { provideDocxEditor } from '@docx-editor.dev/vue';

const props = defineProps<{ bytes: Uint8Array }>();
const { DocxEditorRoot, rootProps, rootListeners, editorRef } = provideDocxEditor({
  document: props.bytes,
});
</script>

<template>
  <button :disabled="!editorRef" @click="editorRef?.save()">Save</button>
  <DocxEditorRoot v-bind="{ ...rootProps, ...rootListeners }">
    <!-- Toolbar, viewport, and content -->
  </DocxEditorRoot>
</template>
MemberTypeUse
DocxEditorRoottypeof DocxEditorRootThe root to render. It provides the shared instance.
rootPropsShallowRef<DocxEditorRootProps> without listenersSpread into v-bind with rootListeners.
rootListenersDocxEditorRootListenersListener props (onReady, onChange, onFontError, onRevisionMarkupChange). Spread into v-bind, not v-on.
editorRefShallowRef<DocxEditorInstance | null>The same instance that useDocxEditor() returns in descendants.

Choose optional components

Mount only the parts that your layout needs. An omitted part renders no interface.

PartPurposeOwner guide
DocxEditorToolbar, DocxEditorMenuFormatting toolbar and menu barToolbar, Menus
DocxEditorHyperLink, DocxEditorContentControl, DocxEditorEquation, DocxEditorContextMenuPopovers. Mount each one you use.Customize popups
DocxEditorHorizontalRuler, DocxEditorVerticalRulerMargin and indent rulers. A drag commits one undo entry.None
DocxEditorNavigationHeadings, Find, and Bookmarks pane. Uses its t prop, else the translate of DocxEditorRoot, else the locale catalog.Navigation
DocxEditorLoadingLoading screen and open overlayCustom loading screen
DocxEditorPageSetupDialog, DocxEditorParagraphDialogControlled dialogs with open and @closeDialogs
DocxEditorPageNumberCurrent and total page countNone
DocxEditorHeaderFooterChrome, DocxEditorNotesChromeHeader, footer, and note editing controlsHeaders and footers
DocxEditorFontNoticeFamilies without a compatible faceFonts
DocxEditorOpenFailureWhy a file did not openOpen failures
DocxEditorDocumentOutlineStandalone heading listNavigation
DocxEditorAuthorStyle, DocxEditorColorByChangeTypeReview colorsReview styling
DocxEditorWindowMoves wrapped parts to a pop-out windowPop-out windows
DocxEditorReview (Pro)Comment and tracked-change cardsReview cards
CustomNodeChrome (Pro)Custom-node markers and menu rowsCustom nodes

Mount popovers

DocxEditorRoot does not mount the four popovers that <DocxEditor> mounts. Add each one as a child of DocxEditorViewport, or register it in the popups prop:

<script setup lang="ts">
import {
  DocxEditorContentControl,
  DocxEditorContextMenu,
  DocxEditorEquation,
  DocxEditorHyperLink,
  DocxEditorRoot,
  definePopup,
} from '@docx-editor.dev/vue';

defineProps<{ bytes: Uint8Array }>();

const popups = {
  hyperlink: definePopup(DocxEditorHyperLink),
  contentControl: definePopup(DocxEditorContentControl),
  equation: definePopup(DocxEditorEquation),
  contextMenu: definePopup(DocxEditorContextMenu),
};
</script>

<template>
  <DocxEditorRoot :document="bytes" :popups="popups">
    <!-- Toolbar, viewport, and content -->
  </DocxEditorRoot>
</template>

Without DocxEditorHyperLink, the link button, the Insert link row, and Ctrl+K open nothing. Without DocxEditorContextMenu, a right-click opens the browser menu.

Custom loading screen

DocxEditorLoading shows before the bytes arrive and while a large document opens. This example replaces the spinner and covers the previous document during a reopen:

<div style="position: relative">
  <DocxEditorViewport>
    <DocxEditorContent />
  </DocxEditorViewport>
  <DocxEditorLoading overlay>
    <template #indicator>
      <MyLogoSpinner label="Opening document" />
    </template>
  </DocxEditorLoading>
</div>

The default slot replaces the whole first screen; the indicator slot replaces only the spinner. Keep DocxEditorContent mounted while the open completes. For the loading flow, see Loading and saving.

Override a component

A named child replaces the matching slot in the preset. hidden removes it, and as-child merges the part's behavior into your element:

<DocxEditorToolbar>
  <DocxEditorToolbar.Bold as-child>
    <MyButton variant="ghost">Bold</MyButton>
  </DocxEditorToolbar.Bold>
  <DocxEditorToolbar.Highlight hidden />
</DocxEditorToolbar>

as-child passes handlers, disabled state, and accessibility attributes to one child element without a wrapper. A group whose slots are all hidden disappears with its separator.

Custom toolbar

Set :preset="false" to render only the parts that you list, in template order:

<DocxEditorToolbar :preset="false" class-name="my-toolbar">
  <DocxEditorToolbar.Undo />
  <DocxEditorToolbar.Redo />
  <DocxEditorToolbar.Separator />
  <DocxEditorToolbar.FontFamily />
  <DocxEditorToolbar.Bold />
  <DocxEditorToolbar.Zoom />
</DocxEditorToolbar>

Each part reads enabled state, active state, and commands from the engine. For DocxEditorToolbar.Group, DocxEditorToolbar.Slot, and DocxEditorToolbar.Action, see Customize the toolbar. For every slot and named part, see the chrome slot reference.

Control lifetime and focus

DocxEditorRoot reads its props at construction. This table shows how each prop behaves after a change:

Prop or eventTypeBehavior
documentDocumentSourceRebuilds the editor.
imageDecodePortImageDecodePortRebuilds the editor.
modulesreadonly EditorModule[]Ignored. Change the :key to remount with new modules.
fontsFontConfiguration | FontConfigurationFragment | FontResolverReplaces fonts in place.
authorstringApplies to later comments and changes. Existing revisions keep their authors.
localestringUpdates date input and labels. Defaults to en-US.
mode'edit' | 'view' | 'suggesting'Updates in place.
zoom, zoomModenumber, ZoomMode | 'auto'Updates in place.
colorMode'light' | 'dark' | 'system'Updates the chrome theme, including dialogs and pop-out windows.
translate(key, params?) => stringUpdates surface labels in place.
tableInteractionLabel(key) => stringResolves table insertion and select-handle labels.
popupsPopup mapLists popups that DocxEditorContent renders.
@ready, @change, @font-errorEventsReport readiness, document changes, and font errors.

In-place updates keep edits, the caret, and undo history. For exact types, see the Vue API reference.

A mousedown that reaches the pages moves the caret. Prevent it on custom chrome, but not on form fields:

<script setup lang="ts">
function keepCaret(event: MouseEvent) {
  const tag = (event.target as HTMLElement | null)?.tagName;
  if (tag === 'INPUT' || tag === 'SELECT' || tag === 'TEXTAREA') return;
  event.preventDefault();
}
</script>

<template>
  <div @mousedown="keepCaret"><!-- Your toolbar --></div>
</template>

Packaged chrome already applies this rule.

Limits

  • DocxEditorContent must be inside DocxEditorViewport, and the viewport needs a bounded height.
  • Composed editors mount popovers explicitly or register them in popups.
  • A composed DocxEditorMenu takes open-handler and save-handler. The packaged <DocxEditor> emits @open and @save instead.
  • The file.pageSetup and paragraph.dialog slots do not open a dialog. Their execute() returns false.
  • Use isLoading, not isOpening, to mount content conditionally. Both flags can read false briefly while the instance changes.
  • Place DocxEditorNavigation inside DocxEditorViewport, or beside it in a row with position: relative.
  • DocxEditorNavigation overlays the page when less than 320 pixels remain beside it. Visible review space reduces that room. With review overflow: 'scroll', only the marker strip counts.
  • Give the viewport's parent position: relative for DocxEditorPageNumber. An indicator inside the viewport renders into that parent.
  • With the context-menu preset enabled, unmatched children appear after the packaged rows.
  • Do not set z-index on the workspace row or viewport. It can trap the context menu under other chrome.
  • as-child requires exactly one child element.
  • Theme chrome with --doc-* tokens. Do not target docx-* classes or theme the document canvas. See Appearance.

See also