Right-to-left text

You can open and edit Arabic, Hebrew, Persian, and Urdu documents with right-to-left (RTL) or mixed-direction text. Change paragraph direction through the toolbar, keyboard, or browser Editor API.

How the editor reads direction

A DOCX file stores direction at two levels. The editor reads both levels:

Alignment and indents name the leading and trailing sides of a paragraph. In an RTL paragraph, w:jc="left" aligns to the right margin. The w:ind w:left property indents from the right. First-line and hanging indents count from the right indent. The kashida justification values justify the paragraph.

List levels follow the same rule. In an RTL paragraph, a level's w:ind w:left indents from the right margin. The w:lvlJc="left" property aligns the marker's right edge with its position. The marker text reads right to left. For example, 1. shows its period on the left. The hebrew1, hebrew2, arabicAlpha, arabicAbjad, and hindiNumbers formats number in their own scripts.

Tab stops count from the right margin, and the text on each side of a tab stays in reading order.

Trailing ordinary spaces (U+0020) stay beside the text whose direction they follow. Their direction determines whether they extend outside the width used for alignment. The editor preserves these spaces in document text. Tabs and nonbreaking spaces (U+00A0) retain their width.

An inline picture reads in the direction of the text on both sides of it. Between text of different directions, or before the first text of a paragraph, it reads in the paragraph's direction. After the last text of a paragraph, it reads in the direction of that text. In an RTL paragraph, a picture before the text stands at the right, and a picture after left-to-right text stands to the right of that text.

A click past the end side of a line, where the paragraph mark stands, places the caret at the end of the line. A click past the start side places the caret on that side of the picture or text at the edge.

The ruler mirrors for an RTL paragraph. The first-line, hanging, and Before text handles appear on the right. The After text handle appears on the left. The Paragraph dialog's Before text and After text fields edit w:ind w:left and w:ind w:right.

Complex-script formatting

A run with w:rtl or w:cs uses complex-script properties for every character. This includes digits and Latin letters:

• w:rFonts w:cs or w:cstheme selects the font. With neither, the run uses Times New Roman.
• w:szCs sets the size. With no w:szCs, the run is 10 pt.
• w:bCs and w:iCs set bold and italic.

w:sz, w:b, and w:i have no effect on such a run. A run without w:rtl or w:cs uses the Latin properties, even for Arabic or Hebrew characters.

Formatting commands use the effective w:rtl and w:cs values, including character styles, paragraph styles, table styles, and document defaults. Direct false values override inherited values. For complex-script runs, commands write both property variants. For example, Bold writes <w:b/><w:bCs/>. It writes <w:b/> on a left-to-right (LTR) run. Selection formatting, caret typing, paragraph marks, format painter, and automation font writes follow this rule.

Change paragraph direction

You can change the direction of the paragraphs in the selection in four ways:

• Toolbar: the Left-to-right text and Right-to-left text buttons follow the alignment control. A mixed selection shows neither button as pressed.
• Format menu: the same two commands follow the alignment rows.
• Paragraph dialog: the Direction setting.
• Keyboard: press Ctrl+Right Shift for RTL and Ctrl+Left Shift for LTR. The command runs when you release the keys. If you press another key or click before you release them, the command does not run. On macOS, use the Control key.

The shortcuts require an RTL paragraph or run in the document region you edit. This requirement avoids overriding Ctrl+Shift keyboard-layout switching in other documents.

The command changes only the paragraph direction. It does not change the text, the run direction, or w:jc. A paragraph aligned to its start moves to the other margin. Paragraphs in table cells change too.

Change direction from code

Use the browser Editor API's setParagraphDirection command. It applies to every paragraph that the selection touches. The command creates 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 writes these values:

Protected and read-only documents refuse the command, like other paragraph formatting. The setParagraphFormat command also accepts direction.

To read the direction at the selection, use the formatting snapshot. When selected paragraphs disagree, the snapshot omits direction and sets disagrees.direction to true.

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

To build your own buttons, use the direction.ltr and direction.rtl chrome slots.

Export RTL text to PDF

PDF export preserves Arabic joining across formatting runs and uses fonts that support Arabic shaping. The PDF text layer keeps Arabic, Persian, and Hebrew words in logical order for text extraction. Default fallback fonts cover Arabic and Hebrew when the selected font lacks those characters.

For font configuration, see Configure PDF fonts. For supported content, see Word feature support.

Numeric fields and note marks

Page fields and note marks containing ASCII decimal digits preserve the surrounding text order. This includes footnote references. Multi-digit values remain one character in the document model. Their display width and navigation remain intact.

This support applies to projected fields and note marks with one-character model ranges. Form controls and other projected content retain their existing layout limits.

Limits

• The editor does not add w:rtl to typed text. Text that you type in an RTL run keeps that run's direction.
• Section direction (w:sectPr/w:bidi) and run direction wrappers (w:dir, w:bdo) do not change layout.
• A paragraph that anchors a floating picture keeps left-to-right order for its text.
• The editor interface does not mirror for RTL languages.