Handle files that do not open

The editor refuses a file that it cannot open safely, such as a damaged archive or a file that is not a .docx document. A refused file leaves the pages blank. The open-failure dialog tells the reader what happened and shows a stable error code.

<DocxEditor> shows the dialog by default. The dialog text is generic and names no contact address. You add your own support actions, such as a link to your help page.

How a refused open is reported

The editor reports a refused open in three places:

openFailure stays set until the next document starts to open. Each refusal is a new object, so a second refusal of the same file shows the dialog again.

The reason groups the codes by what a person can do:

The packaged messages are translated into every bundled language. The keys are under openFailure in @docx-editor.dev/i18n. To change a string in every editor, override its key in the catalog that you pass to i18n. For more information, see @docx-editor.dev/i18n. To change it for one editor, use the options in Change the text.

Add your own buttons

Pass renderOpenFailureActions in React, or fill the #openFailureActions slot in Vue, to add buttons before Close. When you compose the editor from parts, pass the same function as actions to DocxEditor.OpenFailure. Build each button from DocxEditor.OpenFailure.Action, so it matches the dialog. Set variant="primary" for the main action. Close is filled when it is the only button, and outlined beside your own.

With asChild, Action styles your own element instead, such as a link. With dismiss, it closes the dialog after your click handler runs. To keep the dialog open, call event.preventDefault() in the handler.

import { DocxEditor } from '@docx-editor.dev/react';

export function Editor({ bytes }: { bytes: Uint8Array }) {
  return (
    <DocxEditor
      document={bytes}
      renderOpenFailureActions={({ failure }) => (
        <>
          <DocxEditor.OpenFailure.Action asChild>
            <a href={`/support?code=${failure.code}`}>Get help</a>
          </DocxEditor.OpenFailure.Action>
          <DocxEditor.OpenFailure.Action
            variant="primary"
            dismiss
            onClick={() => reportOpenFailure(failure.code)}
          >
            Report the problem
          </DocxEditor.OpenFailure.Action>
        </>
      )}
    />
  );
}

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

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

<template>
  <DocxEditor :document="bytes">
    <template #openFailureActions="{ failure }">
      <DocxEditorOpenFailureAction as-child>
        <a :href="`/support?code=${failure.code}`">Get help</a>
      </DocxEditorOpenFailureAction>
      <DocxEditorOpenFailureAction
        variant="primary"
        dismiss
        @click="reportOpenFailure(failure.code)"
      >
        Report the problem
      </DocxEditorOpenFailureAction>
    </template>
  </DocxEditor>
</template>

reportOpenFailure is your own function. Send the code, not the file. To ask for the file, tell the reader how to send it in your own words.

Change the text

Each option is a property of the openFailure object on <DocxEditor>, and a prop of DocxEditor.OpenFailure.

The next example writes a message for each reason and hides the code:

import type { DocumentOpenFailure } from '@docx-editor.dev/react';

const MESSAGES: Record<DocumentOpenFailure['reason'], string> = {
  damaged: 'This file is damaged. Upload a new copy.',
  'not-docx': 'Upload a .docx file.',
  'too-large': 'This file is too large for the browser editor.',
  blocked: 'This file uses features that we do not allow.',
  unknown: 'We could not open this file.',
};

<DocxEditor
  document={bytes}
  openFailure={{
    title: 'Upload failed',
    message: (failure) => MESSAGES[failure.reason],
    showCode: false,
  }}
/>;

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

defineProps<{ bytes: Uint8Array }>();

const MESSAGES: Record<DocumentOpenFailure['reason'], string> = {
  damaged: 'This file is damaged. Upload a new copy.',
  'not-docx': 'Upload a .docx file.',
  'too-large': 'This file is too large for the browser editor.',
  blocked: 'This file uses features that we do not allow.',
  unknown: 'We could not open this file.',
};

const openFailure = {
  title: 'Upload failed',
  message: (failure: DocumentOpenFailure) => MESSAGES[failure.reason],
  showCode: false,
};
</script>

<template>
  <DocxEditor :document="bytes" :open-failure="openFailure" />
</template>

Replace the dialog content

Pass children in React, or the default slot in Vue, to replace the header, body, and footer. The dialog keeps its frame, focus handling, and Escape. The content receives failure, the packaged message, and dismiss.

<DocxEditor.Root document={bytes}>
  <DocxEditor.OpenFailure>
    {({ failure, message, dismiss }) => (
      <div className="upload-error">
        <h2>{message}</h2>
        <p>Reference: {failure.code}</p>
        <DocxEditor.OpenFailure.Action variant="primary" dismiss onClick={openFilePicker}>
          Choose another file
        </DocxEditor.OpenFailure.Action>
      </div>
    )}
  </DocxEditor.OpenFailure>
  <DocxEditor.Viewport>
    <DocxEditor.Content />
  </DocxEditor.Viewport>
</DocxEditor.Root>

<template>
  <DocxEditorRoot :document="bytes">
    <DocxEditorOpenFailure v-slot="{ failure, message, dismiss }">
      <div class="upload-error">
        <h2>{{ message }}</h2>
        <p>Reference: {{ failure.code }}</p>
        <DocxEditorOpenFailureAction variant="primary" dismiss @click="openFilePicker">
          Choose another file
        </DocxEditorOpenFailureAction>
      </div>
    </DocxEditorOpenFailure>
    <DocxEditorViewport>
      <DocxEditorContent />
    </DocxEditorViewport>
  </DocxEditorRoot>
</template>

openFilePicker is your own function, such as one that clicks a hidden file input. With dismiss, the action closes the dialog after it runs.

If you compose the editor from parts, the dialog is not included. Add DocxEditor.OpenFailure inside DocxEditor.Root, as in the previous example.

Show the failure in your own UI

To show a toast or a banner instead of a dialog, turn off the packaged dialog with openFailure={false}. If you keep both, each has its own dismiss state, and the reader must close both. Then read the failure with useOpenFailure inside DocxEditor.Root. It returns the failure, the packaged message, and dismiss.

Children of <DocxEditor> render in the scroll area, after the pages. To place a banner in another position, compose the editor from parts and put the banner before DocxEditor.Viewport. A toast library that renders into its own container works in either form.

import { DocxEditor, useOpenFailure } from '@docx-editor.dev/react';

function OpenFailureBanner() {
  const { failure, message, dismiss } = useOpenFailure();
  if (!failure) return null;
  return (
    <div role="alert" className="banner">
      {message} ({failure.code})
      <button type="button" onClick={dismiss}>
        Dismiss
      </button>
    </div>
  );
}

<DocxEditor document={bytes} openFailure={false}>
  <OpenFailureBanner />
</DocxEditor>;

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

const { failure, message, dismiss } = useOpenFailure();
</script>

<template>
  <div v-if="failure" role="alert" class="banner">
    {{ message }} ({{ failure.code }})
    <button type="button" @click="dismiss">Dismiss</button>
  </div>
</template>

dismiss hides the current refusal. The next refusal shows again, even for the same file. When a toast closes later than it opened, pass the failure that it showed, as in dismiss(failure). Then a late close cannot hide a newer refusal.

The dialog is an alert, so a click on the backdrop does not close it. Close, your own actions, and Escape close it.

Style the dialog

The dialog uses the shared dialog classes. For more information, see Customize popups.