Tiptap text direction: keep a paragraph override when the document uses auto

Consider an original equipment handout with an Arabic introduction followed by an English identifier such as Probe P-17. Letting each paragraph choose its direction is a useful default. A paragraph beginning with an English identifier, however, may need an author's explicit RTL choice because its main instruction is Arabic. Preserve that choice on the document node instead of forcing the whole editor to face right.

Configure the default on the editor

For an application already using compatible Tiptap 3 packages:

import { Editor } from '@tiptap/core';
import StarterKit from '@tiptap/starter-kit';

const editor = new Editor({
  element: document.querySelector('#handout'),
  extensions: [StarterKit],
  textDirection: 'auto',
  content: '<p>Probe P-17</p><p>افحص الجهاز قبل الاستخدام.</p>'
});

The second sentence asks the reader to inspect the device before use. The content is an illustrative handout, not a device manufacturer's procedure. Retain the application's actual schema, extension list, and storage integration when applying the configuration.

The global option accepts ltr, rtl, and auto. Leaving it undefined adds no global direction attribute. Under auto, the first strong directional character determines a node's direction, so leading digits or punctuation should not be treated as a language detector. This choice applies to content; translating the application toolbar requires a separate interface decision.

Store an exception on the intended paragraph

Place the selection within the paragraph to change. An external toolbar button can restore editor focus before running the command:

function makeSelectedParagraphRTL() {
  editor.chain().focus().setTextDirection('rtl').run();
}

function useDocumentDirectionAgain() {
  editor.chain().focus().unsetTextDirection().run();
}

Connect these handlers to buttons with type="button". A selection spanning several blocks may affect several nodes. If an application already knows the target document position, the command API also accepts a position or a { from, to } range. Positions belong to the current document; do not keep an old number after preceding edits without mapping it.

Choose an explicit RTL override for the mixed paragraph, then inspect editor.getJSON() and editor.getHTML() before saving. Look for the direction on the intended node and confirm the separate English identifier paragraph retains its own behavior. A reader stylesheet that merely right-aligns the text cannot prove the choice was saved.

Reset the paragraph to the configured default

setTextDirection('auto') chooses automatic direction on the target nodes. unsetTextDirection() clears a direction override so the editor's configured default can apply. With the global setting above, clearing an RTL override in Tiptap 3.32.0 restores dir: 'auto' in the node data and dir="auto" in exported HTML. Do not assume clearing an exception leaves every representation without a direction attribute. Unset command reference

Name toolbar actions accordingly. “Use document direction” is clearer for removing an exception than a button labeled “LTR” that resets the override. After removing the override, inspect the stored representation as well as the visible paragraph.

The Tiptap alignment guide covers where lines sit in a block. Keep alignment separate from direction so an author can center a heading without changing the order of mixed-language text. For isolated names and punctuation in the final HTML, use the HTML direction and bidi guide.

Reopen the recipient's handout

Save the application's usual HTML or JSON representation, reopen it with the compatible editor configuration, and read both paragraphs without touching the direction buttons. Check that an explicit exception survives while a cleared exception follows the default. If the editor output contains dir but the saved record loses it, inspect the storage sanitizer rather than adding a visual workaround.

Finally read the delivered handout at phone width. Verify the identifier remains Probe P-17, the Arabic instruction retains its punctuation, and the two paragraphs stay distinct. The useful result is a readable saved handout, with its author-selected exceptions intact.