Right-to-left support

The editor opens, edits, and exports right-to-left (RTL) and mixed-direction text, such as Arabic, Hebrew, Persian, and Urdu. Interface language, locale, and document direction are independent. An English interface does not change RTL document layout.

Editor interface

Show the interface in Arabic or Hebrew

Pass the ar or he catalog. These catalogs declare _dir: 'rtl', so the controls mirror without a wrapper element.

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

<DocxEditor document={bytes} i18n={ar} locale="ar-SA" />;

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

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

<template>
  <DocxEditor :document="bytes" :i18n="ar" locale="ar-SA" />
</template>

In a composed editor, wrap DocxEditor.Root in LocaleProvider. Vue uses <LocaleProvider :i18n="ar"> the same way.

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

<LocaleProvider i18n={ar}>
  <DocxEditor.Root document={bytes}>{/* Toolbar, viewport, and other parts */}</DocxEditor.Root>
</LocaleProvider>;

In an RTL interface, the toolbar, menus, dialogs, and rulers mirror. The navigation pane opens at the right, and the review column moves to the left of the page.

Choose the interface direction

LocaleProvider picks the direction from the first of these that applies:

1. Its dir prop, 'ltr' or 'rtl'.
2. The catalog's _dir flag.
3. An RTL _lang tag in the catalog, such as fa or ur.
4. The direction of an outer LocaleProvider.

Otherwise the interface inherits the host page direction. Shipped LTR catalogs, such as en, declare no _dir, so they inherit too. On an RTL host page, pass dir="ltr" for an LTR interface.

To mirror the interface for your own catalog, add _dir:

import type { Translations } from '@docx-editor.dev/i18n';

const persian: Translations = {
  _lang: 'fa',
  _dir: 'rtl',
  // Translated strings
};

New right-to-left documents

Pass direction to blankDocumentBytes(). The optional bidiLanguage sets the default language of RTL text and ignores values that are not language tags.

import { blankDocumentBytes } from '@docx-editor.dev/core/editor';

const bytes = blankDocumentBytes({ direction: 'rtl', bidiLanguage: 'ar-SA' });

The paragraphs and section read right to left. The interface language never changes the direction of an existing document.

Change paragraph direction

Run setParagraphDirection on the browser Editor. It changes every paragraph that the selection touches, in one undo step.

import type { Editor } from '@docx-editor.dev/core';

function makeRightToLeft(editor: Editor) {
  const command = { type: 'setParagraphDirection', direction: 'rtl' } as const;
  const permission = editor.can(command);
  return permission.ok ? editor.exec(command) : permission;
}

• The command does not change the text, the run direction, or w:jc.
• Protected and read-only documents refuse it. setParagraphFormat also accepts direction.
• The toolbar slots are direction.ltr and direction.rtl. For more information, see Chrome slot reference.
• In the interface, Ctrl+Right Shift sets RTL and Ctrl+Left Shift sets LTR, when the edited region already has RTL text.

Read the direction from the formatting snapshot. A mixed selection omits direction and sets disagrees.direction to true.

const formatting = editor.snapshot().formatting;
const direction = formatting?.direction ?? (formatting?.disagrees?.direction ? 'mixed' : 'ltr');

For document automation on a server or in the browser, use Paragraph.readingOrder. For more information, see Right-to-left paragraphs.

Build direction-aware controls

Read the interface direction with useChromeDir() from the adapter package.

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

const dir = useChromeDir(); // 'ltr' | 'rtl' | undefined

• undefined means the interface inherits the host page direction. Read the computed direction of your element.
• In Vue, useChromeDir() returns a readonly shallow ref. Read .value in script.
• Outside the editor, chromeDirection(dir, catalog, inherited), catalogDirection(catalog), and localeDirection(tag) from @docx-editor.dev/i18n apply the same rules.
• Use logical CSS properties, such as margin-inline-start and inset-inline-end. Physical left and right and custom directional icons do not mirror.

On an RTL host page, set the dir attribute, not only the CSS direction property. The review column and navigation pane read the nearest dir attribute. The pages keep an LTR base, and only w:bidi and w:rtl set text direction.

If you attach the editor to your own scroll container instead of DocxEditor.Viewport, set direction: ltr on it. Otherwise horizontal scrolling and zoom follow the host direction.

Configure PDF fonts

PDF export keeps Arabic joining and writes Arabic, Persian, and Hebrew text in logical order. Default fallback fonts cover Arabic and Hebrew.

Browser fonts do not configure the PDF server. For server fonts, see Configure PDF fonts.

Limits

• The editor has no command to add or remove w:bdo or w:dir wrappers. Saving keeps existing wrappers.
• A paragraph with a positional tab (w:ptab) keeps LTR order for its text.
• Kerning and cursive offsets across formatting run boundaries are not applied.
• Section direction changes only the column order.
• Typing Arabic or Hebrew letters into an LTR run starts a w:rtl run. The first typed letter decides; digits, spaces, and punctuation alone keep the run direction.
• The typed text and its w:rtl change form one undo step, and collaboration peers receive both.
• Clear Formatting and the format painter keep the target run's w:rtl.
• Shaping, digit order, complex-script defaults, and table geometry follow DOCX feature support.

See also

• Interface translations
• Chinese, Japanese, and Korean text
• Configure PDF fonts