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>| Requirement | Why |
|---|---|
DocxEditorRoot | Owns the editor instance. It renders no DOM element, so its children sit in your flex column. |
DocxEditorViewport | Supplies the scroll container. DocxEditorContent must be inside it. |
DocxEditorContent | Mounts the painted, editable pages. |
| Editor stylesheet | Styles the viewport and packaged parts. Import it once. |
| Bounded height | Gives the viewport room. Use flex: 1 and min-height: 0 on the viewport and on any element between it and the container. |
.docx-editor wrapper | Makes 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>| Member | Type | Use |
|---|---|---|
DocxEditorRoot | typeof DocxEditorRoot | The root to render. It provides the shared instance. |
rootProps | ShallowRef<DocxEditorRootProps> without listeners | Spread into v-bind with rootListeners. |
rootListeners | DocxEditorRootListeners | Listener props (onReady, onChange, onFontError, onRevisionMarkupChange). Spread into v-bind, not v-on. |
editorRef | ShallowRef<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.
| Part | Purpose | Owner guide |
|---|---|---|
DocxEditorToolbar, DocxEditorMenu | Formatting toolbar and menu bar | Toolbar, Menus |
DocxEditorHyperLink, DocxEditorContentControl, DocxEditorEquation, DocxEditorContextMenu | Popovers. Mount each one you use. | Customize popups |
DocxEditorHorizontalRuler, DocxEditorVerticalRuler | Margin and indent rulers. A drag commits one undo entry. | None |
DocxEditorNavigation | Headings, Find, and Bookmarks pane. Uses its t prop, else the translate of DocxEditorRoot, else the locale catalog. | Navigation |
DocxEditorLoading | Loading screen and open overlay | Custom loading screen |
DocxEditorPageSetupDialog, DocxEditorParagraphDialog | Controlled dialogs with open and @close | Dialogs |
DocxEditorPageNumber | Current and total page count | None |
DocxEditorHeaderFooterChrome, DocxEditorNotesChrome | Header, footer, and note editing controls | Headers and footers |
DocxEditorFontNotice | Families without a compatible face | Fonts |
DocxEditorOpenFailure | Why a file did not open | Open failures |
DocxEditorDocumentOutline | Standalone heading list | Navigation |
DocxEditorAuthorStyle, DocxEditorColorByChangeType | Review colors | Review styling |
DocxEditorWindow | Moves wrapped parts to a pop-out window | Pop-out windows |
DocxEditorReview (Pro) | Comment and tracked-change cards | Review cards |
CustomNodeChrome (Pro) | Custom-node markers and menu rows | Custom 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 event | Type | Behavior |
|---|---|---|
document | DocumentSource | Rebuilds the editor. |
imageDecodePort | ImageDecodePort | Rebuilds the editor. |
modules | readonly EditorModule[] | Ignored. Change the :key to remount with new modules. |
fonts | FontConfiguration | FontConfigurationFragment | FontResolver | Replaces fonts in place. |
author | string | Applies to later comments and changes. Existing revisions keep their authors. |
locale | string | Updates date input and labels. Defaults to en-US. |
mode | 'edit' | 'view' | 'suggesting' | Updates in place. |
zoom, zoomMode | number, ZoomMode | 'auto' | Updates in place. |
colorMode | 'light' | 'dark' | 'system' | Updates the chrome theme, including dialogs and pop-out windows. |
translate | (key, params?) => string | Updates surface labels in place. |
tableInteractionLabel | (key) => string | Resolves table insertion and select-handle labels. |
popups | Popup map | Lists popups that DocxEditorContent renders. |
@ready, @change, @font-error | Events | Report 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
DocxEditorContentmust be insideDocxEditorViewport, and the viewport needs a bounded height.- Composed editors mount popovers explicitly or register them in
popups. - A composed
DocxEditorMenutakesopen-handlerandsave-handler. The packaged<DocxEditor>emits@openand@saveinstead. - The
file.pageSetupandparagraph.dialogslots do not open a dialog. Theirexecute()returnsfalse. - Use
isLoading, notisOpening, to mount content conditionally. Both flags can readfalsebriefly while the instance changes. - Place
DocxEditorNavigationinsideDocxEditorViewport, or beside it in a row withposition: relative. DocxEditorNavigationoverlays the page when less than 320 pixels remain beside it. Visible review space reduces that room. With reviewoverflow: 'scroll', only the marker strip counts.- Give the viewport's parent
position: relativeforDocxEditorPageNumber. 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-indexon the workspace row or viewport. It can trap the context menu under other chrome. as-childrequires exactly one child element.- Theme chrome with
--doc-*tokens. Do not targetdocx-*classes or theme the document canvas. See Appearance.