Mixed-direction text can look correct in one context and become confusing in another. This guide explains how Unicode bidirectional text works and provides a reusable checklist for debugging Arabic, Hebrew, numbers, punctuation, and left-to-right content in HTML, CSS, JavaScript, forms, chat interfaces, invoices, and code editors.
Overview
Unicode bidirectional text, often called bidi text, describes how a display system arranges characters that have different directional behavior. English is generally written left to right, while Arabic and Hebrew are generally written right to left. Numbers, punctuation, symbols, and embedded Latin product names may follow their own directional rules.
The result is not determined by the visual order of the characters in the source string alone. A browser applies the Unicode Bidirectional Algorithm, then combines that result with the direction of the document, element, and inline content. This is why a sentence containing Arabic text, an invoice number, and a currency symbol can appear scrambled even when the underlying string is intact.
Keep three concepts separate while debugging:
- Text direction: Whether a block or inline run is primarily left to right or right to left.
- Character direction: The directional property assigned to characters by Unicode.
- Layout direction: How CSS places boxes, alignment, margins, icons, and controls.
Changing direction may solve a layout problem without solving an inline-text problem. Conversely, inserting an invisible directional mark may change the display of a string without changing the surrounding layout. Start by identifying which of these layers is failing.
Useful bidi controls and isolation tools
| Control or property | Example | Typical use |
|---|---|---|
| LRM, U+200E | Left-to-right mark | Provides a small left-to-right directional cue near ambiguous punctuation or short inline values. |
| RLM, U+200F | Right-to-left mark | Provides a small right-to-left directional cue when surrounding text needs one. |
| ALM, U+061C | Arabic letter mark | Supports directional behavior near Arabic text and adjacent punctuation. |
| LRI / RLI, U+2066 / U+2067 | Left-to-right or right-to-left isolate | Begins an isolated inline span; close it with PDI, U+2069. |
| FSI, U+2068 | First-strong isolate | Lets the first strong directional character determine an isolated span's direction. |
HTML dir | dir="rtl" | Declares the intended direction of a document or element. Prefer this for semantic direction. |
CSS unicode-bidi | isolate or plaintext | Controls bidi interaction between an element and nearby content; use deliberately. |
For ordinary web content, prefer semantic HTML direction and isolation over manually scattering invisible marks through user-visible strings. Unicode controls remain useful at data boundaries, but they should be documented and tested because they are not visible in ordinary interfaces.
Checklist by scenario
HTML and page structure
- Set the page direction at the document level when the interface has a known primary direction, for example
<html dir="rtl" lang="ar">. - Override direction on genuinely different regions rather than applying one direction to every child.
- Use
dir="auto"for independent user-generated snippets when the first strong character should determine the direction. - Wrap embedded values such as names, ticket numbers, URLs, or quoted messages in a directional boundary.
- Inspect the DOM, not just copied text. A missing wrapper or an unexpected text node can change bidi resolution.
A comment or message containing both languages is often safer as a self-contained element with dir="auto" than as a text fragment concatenated into a larger sentence.
CSS and layout debugging
- Check the computed value of
directionon the affected element and its ancestors. - Use logical properties such as
margin-inline-start,padding-inline-end, andinset-inline-startwhere the design should adapt to direction. - Distinguish text alignment from direction:
text-align: startfollows the inline direction, while a hard-codedleftorrightmay not. - Test flex and grid layouts in both directions. An intentional visual order may require an explicit rule rather than relying on source order.
- Use
unicode-bidi: isolatefor components whose text should not affect surrounding inline ordering. Treatisolate-overrideandbidi-overrideas specialist tools, not defaults.
For an RTL interface, do not assume that every icon should be mirrored. Directional icons such as back arrows may need mirroring, while brand marks, media controls, and some document symbols may need to remain unchanged.
JavaScript and text processing
- Log the exact string and its code points when the display is surprising. A browser-based Unicode lookup tool can help reveal invisible marks.
- Do not use string reversal as an RTL fix. Reversing code units, code points, or grapheme clusters can corrupt text and still produce incorrect display order.
- Keep raw data separate from presentation formatting. Add direction or isolation at the rendering boundary when possible.
- Test concatenation points: labels plus values, values plus punctuation, and translated strings with interpolated variables.
- Use Unicode-aware handling for characters whose visible unit may contain multiple code points. Bidirectional behavior and grapheme boundaries are separate concerns.
When debugging a JavaScript value, compare the stored string with its rendered representation. If the stored code points are correct but the browser display is unexpected, investigate direction, isolation, and adjacent text before changing the data.
Forms, invoices, and transactional content
- Give each field an intentional direction. Names and addresses may use
auto, while account numbers, dates, and structured identifiers often need a stable LTR presentation. - Keep labels and values in separate elements so their direction can be controlled independently.
- Render invoice numbers, order IDs, phone numbers, and URLs inside isolated spans.
- Test punctuation at both ends of values, including parentheses, colons, slashes, hyphens, and currency symbols.
- Verify copying, printing, screen-reader output, and exported text—not only the on-screen layout.
For example, an RTL invoice can use an RTL page and RTL labels while displaying an order identifier in an isolated LTR span. This preserves the document's reading direction without allowing the identifier's punctuation to reorder nearby text.
Chat interfaces and code editors
Chat messages should be treated as independent directional runs. Use dir="auto" or an explicit per-message direction, and isolate usernames, timestamps, reactions, and URLs from message text. Consider a visible direction indicator or a direction toggle when users regularly post short strings whose first strong character is not representative.
Code editors require stricter handling. Display source code in a predictable direction, expose or flag bidi control characters, and avoid silently accepting directional overrides in identifiers, comments, or reviewable source. This is both a readability measure and a security practice; see the guide to Unicode security, homoglyphs, confusables, and safe identifier checks for related checks.
What to double-check
- Encoding: Confirm the document, response, database, and JavaScript source preserve Unicode correctly. Encoding errors are different from bidi ordering errors; use the Unicode encoding debugging checklist when characters are replaced or lost.
- Normalization: Normalization usually does not determine visual direction, but inconsistent text can complicate comparisons, validation, and testing. Review NFC, NFD, NFKC, and NFKD behavior in the Unicode normalization guide.
- Boundaries: Check whether a variable is inserted inside a sentence, next to punctuation, or inside another directional span. Most practical bugs occur at these boundaries.
- Controls: Search for LRM, RLM, ALM, isolate controls, and override controls in copied content. Make them visible in a diagnostic view rather than guessing.
- Responsive behavior: Test narrow widths, wrapping, truncation, ellipses, and overflow. A string can have correct bidi ordering but still fail because a component assumes a single-line LTR label.
- Interaction: Check selection, cursor movement, deletion, copy and paste, validation messages, and keyboard navigation in both directions.
For a compact diagnostic fixture, test a Hebrew or Arabic phrase beside an English product name, a decimal number, a date, parentheses, a URL, and a currency amount. Repeat the fixture in an LTR container, an RTL container, and an element using dir="auto".
Common mistakes
- Reversing the string manually: Visual ordering belongs to the bidi algorithm and layout system. Manual reversal can damage logical text and accessibility.
- Using
text-align: rightas an RTL solution: Alignment changes where a line sits; it does not establish the text direction or isolate embedded values. - Applying
direction: rtlglobally: This can break code, numbers, controls, and components that should remain direction-neutral. - Adding invisible marks without ownership: Marks copied from one context can create new problems elsewhere. Record why a mark exists and test the string at its intended boundary.
- Testing only complete sentences: Short labels, usernames, IDs, punctuation-only values, and numbers expose different behavior.
- Assuming normalization fixes bidi issues: Normalization and direction resolve different classes of Unicode behavior.
- Ignoring security review: Directional overrides and invisible characters can make displayed source or identifiers differ from their logical order. Treat unexpected controls as review findings.
When to revisit
Revisit this checklist whenever an application adds Arabic, Hebrew, Persian, Urdu, or another RTL locale; introduces user-generated text; changes its design system; or replaces a text, form, editor, or rich-content component. It is also worth repeating before a major browser or framework upgrade when bidi behavior, CSS logical properties, text rendering, or editing interactions are part of the affected surface.
Keep a small regression page in the project with mixed-direction fixtures and expected screenshots or DOM assertions. Include plain text, punctuation, numbers, dates, URLs, identifiers, emoji, and copied content. Run it when workflows or tools change, and inspect both visual output and the underlying code points.
The practical sequence is simple: establish the intended direction, isolate embedded values, inspect invisible controls, test boundaries, and verify interaction. If the problem remains, compare the raw string with the rendered DOM and reduce the example until one direction change or one character boundary explains the behavior. For related Unicode investigations, consult the references on code points and UTF-8 or UTF-16, grapheme clusters, and Unicode character properties.