Text Is Not as Simple as It Looks

A customer called سارة الخطيب places an order. Your interface greets her by name, shows her phone number, lists a keyboard with the product code 2047-KB-NL and limits her delivery note to 160 characters. Every one of those values is correct in the database. Several of them can still reach her screen in a different order from the one you stored, and the character limit depends on what you mean by a character.

None of this is exotic. It happens in ordinary interfaces, with ordinary data, the first time a product meets people who do not write the way its authors do. This issue looks at two places where text stops behaving like a simple row of letters: what counts as one character, and which direction a line of text runs.

Like every issue of the guide, it moves through four stages. You reproduce the behaviour in your own browser, understand why it happens, see how to fix it in production code, and leave with material to test your own work.

Part IStage 1 of 4: Reproduce.ReproduceUnderstandFixTest

What is actually one character?

Ask JavaScript how long a family emoji is and it answers 11. Ask a person and they say one. Ask a database, a network request or an HTML maxlength attribute, and you may get yet another number. They are all correct; they are counting different things.

Try the samples below, then paste something of your own: your name, a message in another script, an emoji with a skin tone.

Stage 2 of 4: Understand.ReproduceUnderstandFixTest

Four honest answers to “how long is this?”

Unicode gives every character a number called a code point, written U+0041 for the Latin capital A or U+0645 for the Arabic letter meem. There is room for 1,114,112 of them, from U+0000 to U+10FFFF. A code point is an abstract number; to store or send it, you need an encoding.

UTF-8 stores each code point in one to four bytes. ASCII characters take one byte, Arabic letters two, most other characters in the first 65,536 positions three, and everything above that, including most emoji, four. Files and network payloads are usually UTF-8, so this is the number that matters for size.

UTF-16 stores each code point in one or two 16-bit code units. Code points above U+FFFF need two, called a surrogate pair. JavaScript strings are sequences of UTF-16 code units, and String.prototype.length counts code units, not characters. So do indexing, slice and substring. Iterating a string with for...of or Array.from, on the other hand, walks it by code point.

None of these is what a reader means by a character. A reader sees grapheme clusters: what Unicode Standard Annex #29 calls user-perceived characters. One cluster can hold many code points:

• a letter followed by combining marks, such as e + U+0301 COMBINING ACUTE ACCENT, or an Arabic letter carrying short-vowel marks (harakat), which the Arabic layout requirements describe as visually attached to the letter before them;
• an emoji ZWJ sequence, where U+200D ZERO WIDTH JOINER glues several emoji together, as in the family above;
• a flag, which is a pair of regional indicator letters;
• an emoji with a skin tone modifier or a variation selector;
• a carriage return followed by a line feed.

The modern way to find grapheme clusters in JavaScript is Intl.Segmenter with granularity: 'grapheme'. MDN lists it as Baseline, widely available across browsers since April 2024. The inspector above uses it, and if your browser does not provide it, the inspector says so instead of inventing a number.

There is one more way two strings can disagree. The letter é can be stored as the single code point U+00E9 or as e followed by U+0301. They look identical and compare as different. String.prototype.normalize() converts both to the same form. Try the Combining accent sample above: the inspector flags text that is not in Normalization Form C.

Stage 3 of 4: Fix.ReproduceUnderstandFixTest

Counting and cutting text safely

The mistakes here are rarely dramatic. A character counter that disagrees with the person typing. A preview that ends in a broken emoji or the replacement character (�) because slice cut a surrogate pair in half. A unique username check that treats admin and admin followed by an invisible zero width space as different people. Open Cut it short in Plate A to watch slice split a cluster.

Count and truncate by grapheme cluster wherever the result is shown to a person. When the browser cannot segment, say so or fall back to code points, which never split a surrogate pair:

// One segmenter can be reused for every call.
const segmenter =
  'Segmenter' in Intl ? new Intl.Segmenter(undefined, { granularity: 'grapheme' }) : null;

/** User-perceived characters, or null if this browser cannot tell. */
export function countGraphemes(text) {
  if (!segmenter) return null; // Do not guess: report that you cannot count.
  let count = 0;
  for (const _ of segmenter.segment(text)) count++;
  return count;
}

/** Shortens text without cutting a perceived character in half. */
export function truncate(text, max, ellipsis = '…') {
  if (!segmenter) {
    // Fallback: code points never split surrogate pairs, but can split clusters.
    const points = Array.from(text);
    return points.length <= max ? text : points.slice(0, max).join('') + ellipsis;
  }
  let out = '';
  let count = 0;
  for (const { segment } of segmenter.segment(text)) {
    if (count++ === max) return out + ellipsis;
    out += segment;
  }
  return out;
}

A counter that people can trust uses the same function, reports through a polite live region, and leaves the hard limit to validation rather than silently cutting input:

<label for="bio">Short bio</label>
<textarea id="bio" dir="auto" aria-describedby="bio-count"></textarea>
<p id="bio-count" aria-live="polite">0 of 160 characters</p>

<script type="module">
  import { countGraphemes } from './text.js';

  const LIMIT = 160;
  const bio = document.querySelector('#bio');
  const status = document.querySelector('#bio-count');

  bio.addEventListener('input', () => {
    const used = countGraphemes(bio.value) ?? Array.from(bio.value).length;
    status.textContent = `${used} of ${LIMIT} characters`;
    bio.setCustomValidity(used > LIMIT ? 'Please shorten your bio.' : '');
  });
</script>

Compare text after normalizing it, and remember that normalization is not sanitizing:

// Two strings that look the same can differ in storage.
'\u00E9' === 'e\u0301';                                   // false
'\u00E9'.normalize('NFC') === 'e\u0301'.normalize('NFC'); // true

// Normalization does not remove invisible characters.
'admin\u200B'.normalize('NFC') === 'admin';               // false

Part IIStage 1 of 4: Reproduce.ReproduceUnderstandFixTest

Why does this sentence change direction?

Arabic is written from right to left. Numbers, and words in Latin script such as product names, still run from left to right inside it. That is normal, well-defined behaviour: browsers implement the Unicode Bidirectional Algorithm, and most mixed Arabic and English text renders exactly as a reader expects.

Trouble starts at boundaries. When the browser does not know the base direction of a paragraph, or when an inserted value sits next to text that pulls its characters in another direction, the result can be technically correct and still unreadable. The playground below builds one sentence from three parts. Every rendering you see is produced by your browser from the HTML shown under it.

<!-- inside an element (or page) with dir="rtl" -->
<p>اتصل بنا على +44 20 7946 0123 من الأحد إلى الخميس.</p>

<!-- inside an element (or page) with dir="rtl" -->
<p dir="rtl">اتصل بنا على +44 20 7946 0123 من الأحد إلى الخميس.</p>

<!-- inside an element (or page) with dir="rtl" -->
<p dir="auto">اتصل بنا على +44 20 7946 0123 من الأحد إلى الخميس.</p>

<!-- inside an element (or page) with dir="rtl" -->
<p>اتصل بنا على <bdi>+44 20 7946 0123</bdi> من الأحد إلى الخميس.</p>

Stage 2 of 4: Understand.ReproduceUnderstandFixTest

Base direction, strong characters and neutrals

Text is stored in logical order: the order in which it is read and typed. The bidirectional algorithm works out the visual order for each line. To do that it needs two things: the base direction of the paragraph, and the bidirectional class of every character. The strip in Plate B shows both for whatever you type.

The base direction comes from HTML. An element with dir="rtl" or dir="ltr" sets it explicitly. An element without dir inherits it from its parent, and if no ancestor sets it, it is left to right. With dir="auto", the browser looks for the first character with a strong direction and uses that, skipping things such as nested <bdi> elements and elements with their own dir. This mirrors rules P2 and P3 of the algorithm.

Each character’s class is fixed by Unicode. The ones that matter most in practice:

Three behaviours of the algorithm explain every scenario in the playground.

Neutral characters take sides

A neutral character between two strong characters of the same direction takes that direction. Anywhere else, at the edge of a run, between opposite directions, or at the end of a paragraph, it takes the direction of the paragraph (rules N1 and N2). That is why the slash at the end of https://example.com/ar/ and the exclamation mark at the end of Hello, world! move to the far side in a right-to-left paragraph: as far as Unicode can tell, they belong to the Arabic sentence.

Numbers borrow their context

Digits are weak. After Arabic letters, European digits are treated as Arabic numbers (rule W2); after Latin letters, they are treated as part of the Latin text (rule W7). So KB-2047-NL stays in one piece inside Arabic, while 2047-KB-NL does not: its leading digits attach to the Arabic words before them. In an English sentence, the same rule pulls the : 3 after an Arabic name into the name’s right-to-left run. Groups of digits separated by spaces are separate numbers, so a phone number in a right-to-left paragraph is laid out group by group from right to left. The Arabic layout requirements describe this weak behaviour of numbers and give phone numbers as an example of numerals mixed with spaces and signs.

Brackets are mirrored

In right-to-left text, characters such as (, ), [ and < are drawn with mirrored glyphs (rule L4), and matching pairs of brackets are resolved together (rule N0). In the Parentheses and numbers scenario the parentheses still look right, but the parenthesised offset ends up on the other side of the time.

Block direction and inline direction are different jobs

dir on a block element such as <p> sets the base direction of a paragraph: where lines start, which side neutral characters at the ends fall to, which way the text aligns. dir on an inline element, and the <bdi> element, creates an isolate: a piece of text whose direction is worked out on its own and which, seen from outside, behaves like a single neutral character. According to MDN, isolation works both ways: the text inside does not influence its surroundings, and is not influenced by them.

You can see the difference in the Arabic name followed by an email address scenario. Switch the page direction to RTL: <bdi> still isolates the name, but the English sentence around it is now a right-to-left paragraph, and isolation cannot fix that. The block needs the right direction and the value needs isolation.

Choosing an approach

• Inherit whenever possible. Put lang and dir on the <html> element once and let content inherit it. The W3C recommends doing this in markup rather than with the CSS direction property, and MDN explains why: direction belongs to the content, not its presentation.
• Explicit dir on a block when you know its language, for example an English quotation inside an Arabic page.
• dir="auto" on a block whose direction you cannot know, such as a user comment or a chat message. It is a heuristic: MDN describes it as determining direction from the first strong character, “not language detection”. An English sentence that begins with an Arabic name becomes right to left; an Arabic sentence that begins with an email address becomes left to right; text with no strong characters at all falls back to left to right. If you know the direction, for example from the language a person chose, set it explicitly.
• <bdi> around a value of unknown direction inserted into text you control: names, titles, anything interpolated into a template. It behaves as if dir="auto" were set. MDN notes that <bdi dir="ltr"> and <span dir="ltr"> are exactly equivalent, and that a semantic element with dir="auto", such as <cite dir="auto">, is preferable to <bdi> where one fits.
• dir="ltr" on an inline wrapper for values that are always left to right: phone numbers, product codes, email addresses, URLs, code.

<!-- Set the document direction once, in markup, with the language. -->
<html lang="ar" dir="rtl">

<!-- A block whose direction you know (a quotation in English). -->
<blockquote lang="en" dir="ltr">…</blockquote>

<!-- A block whose direction you do not know (a user comment). -->
<p class="comment" dir="auto">…</p>

<!-- A value of unknown direction inside text you control. -->
<p>تعليق جديد من <bdi>{{ user.name }}</bdi></p>

<!-- A value that is always left to right. -->
<p>للتواصل: <span dir="ltr">+44 20 7946 0123</span></p>

Form fields follow the same logic. The W3C recommends dir="auto" on inputs and textareas so text aligns with what is typed, and the dirname attribute sends the field’s direction to the server along with its value, so you can display it correctly later instead of guessing again. The Arabic Script Gap Analysis records dirname support as fixed in all three major browser engines.

<!-- Let the field follow what the person types... -->
<input name="comment" dir="auto" dirname="comment.dir">

<!-- ...but phone numbers, emails and URLs are left to right. -->
<input type="tel"   name="phone" dir="ltr" autocomplete="tel">
<input type="email" name="email" dir="ltr" autocomplete="email">

Some places cannot contain markup: document.title, title attributes, <option> text, notifications. There, Unicode’s isolate characters do the same job as <bdi> and dir. The W3C’s article on inline markup and bidirectional text recommends markup wherever it is available and isolates (rather than the older embedding controls) where it is not.

// Where markup is impossible (document.title, a title attribute,
// a notification), use Unicode isolates around the inserted value.
const FSI = '\u2068'; // FIRST STRONG ISOLATE: like <bdi> / dir="auto"
const LRI = '\u2066'; // LEFT-TO-RIGHT ISOLATE: like dir="ltr"
const PDI = '\u2069'; // POP DIRECTIONAL ISOLATE: closes either

document.title = `${FSI}${conversation.name}${PDI} · Messages`;
input.title = `رقم الهاتف: ${LRI}${phone}${PDI}`;

Stage 3 of 4: Fix.ReproduceUnderstandFixTest

A production pattern

Isolation is easiest to get right when it is part of how an interface is built rather than a fix applied to individual strings. Here is an order summary from a shop that sells in Arabic and English. Switch to Plain markup to see what happens without isolation, and switch the interface language to see that the same component works in both directions.

<section class="order" dir="rtl" lang="ar" aria-label="ملخص الطلب">
  <header class="order__head">
    <h3>ملخص الطلب</h3>
    <p>طلب رقم <span dir="ltr">#1042</span> · <time datetime="2026-11-02">2 نوفمبر 2026</time></p>
  </header>
  <dl class="order__details">
    <div><dt>العميل</dt><dd><bdi>سارة الخطيب</bdi></dd></div>
    <div><dt>الهاتف</dt><dd><a href="tel:+442079460123" dir="ltr">+44 20 7946 0123</a></dd></div>
    <div><dt>البريد الإلكتروني</dt><dd><a href="mailto:sara@example.com" dir="ltr">sara@example.com</a></dd></div>
  </dl>
  <h4 class="order__subhead">المنتجات</h4>
  <ul class="order__items">
    <li class="order__item">
      <p class="order__title"><bdi>Aurora Mechanical Keyboard, 75% layout</bdi></p>
      <p class="order__meta">رمز المنتج <span translate="no" dir="ltr">2047-KB-NL</span> · الكمية 1</p>
      <p class="order__price"><data value="149.00" dir="ltr">149.00 USD</data></p>
    </li>
    <li class="order__item">
      <p class="order__title"><bdi>USB-C cable (2 m)</bdi></p>
      <p class="order__meta">رمز المنتج <span translate="no" dir="ltr">88-USBC-2M</span> · الكمية 2</p>
      <p class="order__price"><data value="12.50" dir="ltr">12.50 USD</data></p>
    </li>
  </ul>
  <dl class="order__totals">
    <div><dt>الشحن</dt><dd>مجاني</dd></div>
    <div class="order__grand"><dt>الإجمالي</dt><dd><data value="174.00" dir="ltr">174.00 USD</data></dd></div>
  </dl>
  <p class="order__note">سنتواصل مع <bdi>سارة الخطيب</bdi> على الرقم <span dir="ltr">+44 20 7946 0123</span> قبل التوصيل.</p>
</section>

The implementation follows a few rules that hold for most interfaces:

1. The component declares its own language and direction (lang and dir on the root). Everything inside inherits them.
2. Values of unknown direction are wrapped in <bdi>. The customer’s name and product titles come from people and catalogues, so the interface cannot know their direction in advance.
3. Values that are always left to right get dir="ltr". The phone number, email address, order number, product codes and amounts. Any element with a dir attribute is isolated from its surroundings, just like <bdi>.
4. Semantics stay intact. Links remain links (tel: and mailto:), the date is a <time> element with a machine-readable value, prices use <data>, and product codes carry translate="no" so translation tools leave them alone.
5. Layout uses logical CSS properties, so nothing in the stylesheet needs to know which way the interface runs.

.order {
  text-align: start;                 /* not left */
}
.order__note {
  border-inline-start: 3px solid;    /* not border-left */
  padding-inline: 12px;              /* not padding-left/right */
}
.order dd {
  text-align: end;                   /* not right */
}
/* Phone numbers, codes and amounts should not break across lines. */
.order [dir="ltr"] {
  white-space: nowrap;
}
/* When an icon must point "forward", flip it for right-to-left text. */
.icon-forward:dir(rtl) {
  transform: scaleX(-1);
}

Stage 4 of 4: Test.ReproduceUnderstandFixTest

Test it in your own interface

Bidirectional bugs survive code review because the source looks fine. They show up when real data meets real layouts, so the most effective test is to put realistic strings into your interface and look.

A checklist for text and direction

• The <html> element has the right lang and dir, set in markup.
• Every value inserted into a sentence or label is isolated: <bdi> when its direction is unknown, dir="ltr" when it is always left to right.
• User-generated blocks and text fields use dir="auto", and you know which content would fool its first-strong-character heuristic.
• Phone numbers, email addresses, URLs, codes and identifiers render as one left-to-right unit inside right-to-left text.
• Character counters count grapheme clusters, and the client and the server agree on what a limit means.
• Nothing visible to a person is shortened with slice, substring or substr.
• Text is normalized before it is compared, deduplicated or used as a key.
• Where spoofing matters (usernames, file names), bidirectional control characters such as U+202E RIGHT-TO-LEFT OVERRIDE are removed or made visible.
• CSS uses logical properties, and icons that point “forward” are mirrored deliberately.
• The interface has been looked at, not just tested, in both directions, with the fixtures above.

Automating what can be automated

Counting is easy to unit test, because it has exact answers:

import { expect, test } from 'vitest';

const seg = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
const graphemes = (s) => [...seg.segment(s)].length;

test('a family emoji is one character to a reader', () => {
  const family = '\u{1F468}\u200D\u{1F469}\u200D\u{1F467}\u200D\u{1F466}';
  expect(graphemes(family)).toBe(1);
  expect(family.length).toBe(11);
});

Direction is harder. A browser test can check that markup is in place and that an element resolved to the direction you expect, using the :dir() pseudo-class, which the Arabic Script Gap Analysis reports as supported in Gecko, Blink and WebKit:

import { expect, test } from '@playwright/test';

// The inserted name must not change the direction of the sentence around it.
test('customer name is isolated', async ({ page }) => {
  await page.goto('/orders/1042');
  const note = page.locator('.order__note');
  expect(await note.evaluate((el) => el.matches(':dir(rtl)'))).toBe(true);
  await expect(note.locator('bdi')).toHaveText('سارة الخطيب');
});

What no DOM assertion can tell you is the visual order of the characters on screen. For that, use screenshot comparisons of the fixtures in both directions, and a person who reads the language.

Text looks simple because so much work goes into making it look that way. Most of that work is done by Unicode and the browser. The part left to us is small, but it is ours: say what direction things are, keep inserted values apart from the sentences around them, and count characters the way people do.