Dialogs

Register a component with definePopup(). Pass the map through popups on the editor root.

Forward session props to the packaged dialog. Replace named parts with className, hidden, or asChild. Use preset={false} only for a complete arrangement.

Keep a title, error region, Apply action, and Cancel action. Draft hooks provide values, validation, and actions. Apply commits the draft. Cancel discards it.

Popup entries cover page setup, paragraph settings, links, fields, content controls, revision markup, export, and print feedback.

Dialog and popup configuration reference

Use the DOCX editor popup registry to choose automatic renderers. Use named dialog parts to change presentation while retaining the existing draft controller.

Popup registry keys

A false entry disables automatic rendering for that key. It does not disable the underlying operation. For export and print, the operation still runs without its progress surface. When you replace an input popup, provide a usable application path for its operation.

The composed editor explicitly owns hyperlink, content control, equation, and context menu surfaces unless the registry configures them. The packaged editor supplies defaults for those surfaces. An explicit popup entry takes priority over packaged shortcut props.

Dialog parts and draft state

Standard composed dialogs expose Header, Title, Body, Footer, Field, Error, Apply, and Cancel. The revision markup dialog also exposes Reset. Use the specific dialog's exported types to find its valid field names.

The default part's command wiring takes priority over conflicting props. Custom child components must forward supplied attributes, events, and references. Keep Apply, Cancel, errors, and accessible titles in a complete custom arrangement.

The dialog controller exposes values, setValue, errors, isEnabled, apply, and cancel. Apply validates and commits the draft. Cancel discards it. The paragraph controller also reports mixed values. The revision markup controller provides reset. Use the controller for custom inputs instead of writing directly on each keystroke.

Page setup fields

Retain the controller's unit conversion and validation when you replace these inputs. Use Appearance for dialog typography, padding, radius, and gap properties.

Popup lifetime

Keep the renderer's supplied session and close props when you wrap a popup. A session can end when the document loads, the editor detaches, or another session replaces it. Check a session's cancellation signal before an asynchronous action applies its result. Do not retain a draft controller after its dialog closes. The built-in dialog surface manages focus trapping and restores focus when it closes. A separate application modal must preserve those behaviors.

React and Vue reference

Pass your DOCX bytes and loaded fonts to this component. The preview uses a fictional contract.

import { DocxEditor, type DocxEditorRootProps } from '@docx-editor.dev/react';
import { reviewModule, DocxEditorReview } from '@docx-editor.dev/pro/react';
import '@docx-editor.dev/core/styles/editor.css';

const modules = [reviewModule()];

export function ContractEditor({
  bytes,
  fonts,
}: {
  bytes: Uint8Array;
  fonts: DocxEditorRootProps['fonts'];
}) {
  return (
    <div className="docx-editor contract-workspace">
      <DocxEditor.Root
        document={bytes}
        fonts={fonts}
        modules={modules}
        author="Demo reviewer"
        mode="suggesting"
        reviewDisplayMode="all-markup"
      >
        <DocxEditor.Toolbar />
        <DocxEditor.Viewport style={{ height: 520 }}>
          <DocxEditor.Content />
          <DocxEditor.HyperLink />
          <DocxEditor.ContextMenu />
          <DocxEditorReview />
        </DocxEditor.Viewport>
      </DocxEditor.Root>
    </div>
  );
}

<script setup lang="ts">
import { DocxEditor } from '@docx-editor.dev/vue';
import { reviewModule, DocxEditorReview } from '@docx-editor.dev/pro/vue';
import type { FontConfigurationFragment } from '@docx-editor.dev/vue';
import '@docx-editor.dev/core/styles/editor.css';

defineProps<{ bytes: Uint8Array; fonts: FontConfigurationFragment }>();
const modules = [reviewModule()];
</script>

<template>
  <div class="docx-editor contract-workspace">
    <DocxEditor.Root
      :document="bytes"
      :fonts="fonts"
      :modules="modules"
      author="Demo reviewer"
      mode="suggesting"
      review-display-mode="all-markup"
    >
      <DocxEditor.Toolbar />
      <DocxEditor.Viewport :style="{ height: '520px' }">
        <DocxEditor.Content />
        <DocxEditor.HyperLink />
        <DocxEditor.ContextMenu />
        <DocxEditorReview />
      </DocxEditor.Viewport>
    </DocxEditor.Root>
  </div>
</template>

Register your page setup dialog

Create the wrapper in React. Forward the supplied props to retain the editor session.

import { DocxEditor, definePopup } from '@docx-editor.dev/react';
import type {
  DocxEditorPageSetupDialogProps,
  DocxEditorPopups,
  DocxEditorRootProps,
} from '@docx-editor.dev/react';

export function ContractPageSetup(props: DocxEditorPageSetupDialogProps) {
  return (
    <DocxEditor.PageSetupDialog {...props}>
      <DocxEditor.PageSetupDialog.Title>Contract page setup</DocxEditor.PageSetupDialog.Title>
      <DocxEditor.PageSetupDialog.Apply asChild>
        <button type="button" className="contract-apply">
          Apply page settings
        </button>
      </DocxEditor.PageSetupDialog.Apply>
    </DocxEditor.PageSetupDialog>
  );
}

const popups: DocxEditorPopups = {
  pageSetup: definePopup(ContractPageSetup),
};

export function ContractDialogEditor({
  bytes,
  fonts,
}: {
  bytes: Uint8Array;
  fonts: DocxEditorRootProps['fonts'];
}) {
  return (
    <DocxEditor.Root document={bytes} fonts={fonts} popups={popups}>
      <DocxEditor.Menu />
      <DocxEditor.Viewport style={{ height: 520 }}>
        <DocxEditor.Content />
      </DocxEditor.Viewport>
    </DocxEditor.Root>
  );
}

<script setup lang="ts">
import { DocxEditorPageSetupDialog as Dialog } from '@docx-editor.dev/vue';
import type { DocxEditorPageSetupDialogProps } from '@docx-editor.dev/vue';

const props = withDefaults(defineProps<DocxEditorPageSetupDialogProps>(), {
  preset: true,
});
</script>

<template>
  <Dialog v-bind="props">
    <Dialog.Title>Contract page setup</Dialog.Title>
    <Dialog.Apply as-child>
      <button type="button" class="contract-apply">Apply page settings</button>
    </Dialog.Apply>
  </Dialog>
</template>

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

defineProps<{ bytes: Uint8Array }>();
const popups = { pageSetup: definePopup(ContractPageSetup) };
</script>

<template>
  <DocxEditor :document="bytes" :popups="popups" />
</template>

Vue wrappers must preserve preset: true when forwarding omitted Boolean props. The packaged Menu opens Page Setup through its PageSetup part. Use popups.revisionMarkup for the track changes dialog.

.docx-editor .contract-apply {
  padding: 9px 16px;
  border: 0;
  border-radius: 999px;
  background: var(--doc-primary);
  color: var(--doc-on-primary);
}

More control

See Customize popups for supported parts, types, and additional examples.