Inline markup and bidirectional text in HTML

The dir attribute

To set the default direction of the whole HTML document to right-to-left, add dir="rtl" to the html tag. This will result in all elements in the document inheriting a base direction of RTL.

You can change the base direction for content within a page by surrounding that content with an element and adding a dir attribute to indicate the desired direction.

In principle, the right thing to do for every opposite-direction phrase is to set its base direction by using the dir attribute on an element tightly wrapping the phrase.

Check out the worked examples below to see how this works.

LRM/RLM

One use of LRM and RLM is to extend a directional run through neutral or weak characters at the start or end of an opposite-direction phrase, by putting a mark of the same direction as the phrase on the other side of those neutral or weak characters. You can see an example of how it works in the advanced usage notes for use case 1 below.

Another use is to separate an opposite-direction phrase from some neighboring but independent text that would otherwise be incorrectly treated as the same directional run (see use case 3 for a good example). To do this you can put between them a directional mark with the same directionality as the overall context.

In HTML5, where the dir attribute is isolating, both cases are better addressed by adding the dir attribute to an element wrapping the opposite-direction phrase, so there is really no need to use LRM/RLM. See below for details.

dir="auto"

HTML5 provides a new value for the dir attribute: auto. The auto value tells the browser to look at the first strongly typed character in the element. If it's a right-to-left typed character such as a Hebrew or Arabic letter, the element will get a direction of rtl. If it's, say, a Latin character, the direction will be ltr.

There are corner cases where this may not give the desired outcome, but it should usually produce the desired result.

Note that the browser ignores any neutral or weak characters at the beginning of the text when looking for the first strong character. It also ignores anything inside a bdi element or an element with a dir tag of its own, including auto.

Like any other use of the dir attribute in HTML5, dir="auto" also directionally isolates its content from its surroundings.

The bdi element

bdi comes with the dir attribute set to the new auto value by default (see above), however it is also possible to use an explicit dir attribute on bdi with values set to ltr or rtl, if you know the direction of the phrase and just want to isolate it.

The choice of whether to attach dir="auto" on an existing element or to wrap the phrase in a bdi depends on whether you already have an inline element tightly wrapping the potentially opposite-direction phrase, and whether you happen to know the phrase's direction (or can guess at it better than the browser's dir="auto" logic).

The bdo element

There are important use cases for bdo, but they are rare. For more information see Overriding the algorithm below. Do not confuse this element with bdi, and do not use it for managing normal bidi text.

The CSS shim

Browsers that don't yet support the CSS will simply behave in the same way as before, but most recent versions of major browsers do support the desired behavior already.

The CSS shim is as follows:

[dir='ltr'], [dir='rtl'] { 
	unicode-bidi: -webkit-isolate;
	unicode-bidi: -moz-isolate;
	unicode-bidi: -ms-isolate;
	unicode-bidi: isolate;
	} 
bdo[dir='ltr'], bdo[dir='rtl'] {
	unicode-bidi: bidi-override; 
	unicode-bidi: -webkit-isolate-override; 
	unicode-bidi: -moz-isolate-override; 
	unicode-bidi: -ms-isolate-override; 
	unicode-bidi: isolate-override;
  	}

At the time of writing, all browser versions that support isolation in CSS also support the bdi element.

Tightly wrap opposite-direction phrases

The best way to begin to address bidi issues in your content is to tightly wrap every opposite-direction phrase in markup that sets its base direction. By tightly wrap, we mean that the element contains the entire opposite-direction phrase, and nothing but the opposite-direction phrase.

If you know the direction of the phrase

Most of the potential problems pointed out earlier simply melt away when you add a dir attribtue to tightly wrapped phrases of opposite-direction text. When browsers that support the HTML5 specification encounter the dir attribute on an element they isolate the text inside the element from the text surrounding it.

If the phrase is already tightly wrapped in an inline element, you can use the existing element for this purpose. If not, add a span element.

Bulletproofing your code for legacy browsers.

You can bulletproof this approach to handle Edge and Safari or other legacy browsers which still don't directionally isolate elements with a dir attribute. Having tightly-wrapped the phrase as just shown, add a directional mark (RLM or LRM) immediately after the markup of that phrase. Choose one that matches the direction of the surrounding context. This is mostly needed when the phrase is followed by a number or a separate opposite-direction phrase (ie. in a list), but you can add a directional mark matching the direction of the context after every tightly-wrapped phrase.

If you don't know the direction of the phrase

When text will be added at run time to your HTML page you may not be able to predict the base direction of the injected text in advance. To handle this eventuality you have two options.

If the phrase is tightly wrapped by an element already, you could just add dir="auto" to that element. This directionally isolates the element's text and looks at the first strong character to determine what base direction to apply.

Otherwise, wrap the phrase in a bdi element (or in a span element with dir set to auto, if you prefer.) Without a dir attribute, the bdi element behaves as if dir="auto" had been applied.

Bulletproofing your code for legacy browsers.

The isolation can be addressed using LRM/RLM as described above, but the key benefit of the bdi element or dir="auto" is that they can guess at the appropriate base direction for the inserted text.

Unfortunately, there isn't really an alternative way to automatically determine the base direction for the inserted text, other than to use scripting.

Use case 1: Nested bidi

In this example a right-to-left book title is embedded in a left-to-right context, and the book title itself contains an embedded left-to-right phrase. Here is the code without any additional bidi markup:

Bad code. Don't copy!

<p>the title is "AN INTRODUCTION TO c++" in arabic.</p>

What one would expect to see is:

Unfortunately, the bidirectional algorithm cannot tell where the boundaries of the nested changes in base direction should be. The result, without help in the markup, is:

Fixing use case 1

To address this in HTML5, if there is no other markup around the opposite-direction phrases, wrap both in markup with the appropriate dir value. (Note, by the way, how the markup appears inside the quotation marks, which are part of the English text.)

It is important to note that each phrase is nested. Just wrapping the Arabic in one span followed by a span containing the C++ would result in no improvement at all.

advanced usage notes: Note that two elements with dir are needed in this case. This is because there are two opposite-direction phrases. If only one was used, like this:

Bad code. Don't copy!

<p>the title is "<span dir="rtl">AN INTRODUCTION TO c++</span>"</p>

the displayed text would be as shown below. This moves the C++ to the left, as needed, but the + signs appear on the wrong side of the C.

This fails because the "C++" is an opposite-direction (LTR) phrase within the title, ending in neutral characters and the phrase is now being displayed with an RTL base direction. The bidi algorithm has no way of knowing that the plus signs are part of an LTR phrase, not of the RTL context, and thus displays them to the left of the "C" instead of to its right.

To solve this problem, wrap the overall RTL phrase in a <span dir="rtl">, and the LTR phrase nested inside it in its own <span dir="ltr">, as shown.

If there is already suitable markup to surround the book title, such as a cite element, add the dir attribute to that.

Bulletproofing for legacy browsers

The solution outlined for HTML5 aware browsers will work equally well for browsers that don't support HTML5 features.

Use case 2: Following numbers

In the next example, the opposite-direction phrase is followed by a logically separate number. This is the code without any bidi markup:

Bad code. Don't copy!

<p>we find the phrase 'INTERNATIONALIZATION ACTIVITY' 5 times on the page.</p>

You would expect to see:

You would actually see:

This happens because the bidi algorithm tells the browser to treat the "5″ as part of the Hebrew text. This is not appropriate here though. We need to find a way to say that the name and the number are separate things, ie. to isolate the inserted name from the number.

Fixing use case 2

Wrap the opposite-direction phrase (the title) in markup and add the appropriate dir value. There is no need to add anything else, since the dir attribute automatically isolates its content.

If there is already suitable markup to surround the book title, such as an a element, add the dir attribute to it.

Bulletproofing for legacy browsers

For browsers where dir doesn't isolate, you would fix this by not only adding the markup around the opposite direction, Hebrew text, but adding also an LRM character after it. That would prevent the number being associated with the right-to-left text.

If the search string was already tightly wrapped by an element, use that element tag to add the dir attribute, and add the LRM character after it.

Of course, if the overall context is right-to-left, eg. Arabic/Hebrew/etc. text, and the book title was in English, you would need to add an RLM character rather than an LRM character.

Use case 3: Lists

Neutrals between same directional runs can sometimes be misinterpreted by the bidi algorithm. In this use case we have several country names in Arabic listed in a LTR paragraph. This is an example of an opposite-direction phrase followed by another, but logically separate, opposite-direction phrase. Here is the source code without any bidi markup:

Bad code. Don't copy!

<p>the names of these states in arabic are EGYPT, BAHRAIN and KUWAIT respectively.</p>

We expect to see the following:

In the actual result, the first two Arabic words are reversed and the intervening comma is moved to the right side of the space between the words.

The reason for the failure is that, with a strongly typed right-to-left (RTL) character on either side, the bidirectional algorithm sees the neutral comma as part of the Arabic text. It is interpreting the first two Arabic words and the comma as a single directional run in Arabic. In fact it is part of the English text, and should mark the boundary between the two separate right-to-left directional runs in Arabic.

The solution for this use case is similar to that for the previous use case, so we will keep the notes below brief, and assume that you have read the solutions for use cases 1 and 2. We will present just the default markup approach.

Fixing use case 3

Simply wrap each Arabic word with markup and add the appropriate dir value.

If there is already markup surrounding the Arabic text, such as an a element, add the dir attribute to it.

Bulletproofing for legacy browsers

Add markup around the Arabic text, but add also an LRM character after it whenever that text is followed by another opposite-direction phrase. Use an RLM character if the surrounding context is right-to-left.

As before, if the Arabic text was already tightly wrapped by an element, use that element tag to add the dir attribute.

Use case 4: Nested bidi

In the article Structural markup and right-to-left text in HTML there is an example of a page for an online book store that carries books in many languages and needs to display the original book titles regardless of the language of the user interface. Thus, a Hebrew or Arabic book title may appear in an English interface, and vice-versa.

Let us suppose that you searched for the book הצהרות קידוד תװי CSS and and let's further suppose that that book wasn't found. The bookstore might generate a message that says so. The image below shows what one would expect to see.

Note how the 'CSS' is to the left of the Hebrew text because it is part of the book title. However with the following source code ...

Bad code. Don't copy!

<p>your search - <cite class="booktitle">CHARACTER ENCODING IN css</cite> - did not match any documents.</p>

... here is the actual result. Note how the 'CSS' is now on the right of the Hebrew text.

Fixing use case 4

The default rule when there is no other element around the injected text, is to wrap it in bdi.

The bdi tag automatically assigns a direction based on the first strong character in the injected string.

If there is another element around the injected text, use dir="auto" or wrap the injected phrase in bdi.

Bulletproofing for legacy browsers

Without HTML5 markup behavior we can't really address this use case using markup, since we need to know in advance the direction of the text. This can only be achieved by knowing the direction of or examining the injected phrase before insertion, and applying the appropriate directional information by scripting.

Use case 5: Following numbers

Here's an example where the names of restaurants are added to a page from a database and followed by a number. You don't know in advance the directionality of the injected text. This is the code produced by the script that injects the phrases, without bidi markup:

Bad code. Don't copy!

<p><span class="name">aroma</span> - 3 reviews</p>
<p><span class="name">PURPLE PIZZA</span> - 5 reviews</p>
<p><span class="name">PURPLE PIZZA roma</span> - 3 reviews</p>

And here's what one would expect to see, and what you'd actually see.

The problem with the second restaurant name arises because the browser thinks that the " – 5″ is part of the Hebrew text. This is what the Unicode Bidi Algorithm tells it to do, and usually it is correct. Not here though. We need to find a way to say that the name and the number are separate things, ie. to isolate the inserted name from the number.

In the third restaurant name the number is back in the right place, but the word 'Roma' is part of the Hebrew name, and should appear to the left of the Hebrew text. In other words, we need to apply a base direction of RTL to the whole of the injected text.

Fixing use case 5

Once again, the default rule when there is no other element around the injected text, is to wrap it in bdi. The bdi element automatically isolates the injected phrase from the number, and sets the direction for the phrase based on its first strong character.

The bdi tag automatically assigns a direction based on the first strong character in the injected string.

You'll notice that the example above puts bdi around the name Aroma too. Of course, you don't actually need that, but it won't do any harm. On the other hand, it simplifies the necessary script code, and means you can handle any name that comes out of the database, whatever script it is in.

If there is another element around the injected text, use dir="auto".

Bulletproofing for legacy browsers

Again, without HTML5 markup behavior, all we can do is add a LRM character after the injected phrase, to ensure that it is isolated from the number. This would be sufficient to correctly render the second item in the list, because it is a very simple case, with no embedded opposite-direction phrases or neutral characters. The third case, however, will not work so well, since the base direction has to be set to right-to-left for the word 'Roma' to appear on the left. This can only be properly rendered if the injected phrase has markup added to it before insertion.

The code would look something like this.

Use case 6: Punctuation at the end of an opposite-direction phrase

It is a very common situation for punctuation or some other neutral character to appear at the end of an opposite direction phrase and belong with that phrase.

Unfortunately, such neutrals between different directional runs are typically misinterpreted unless there is additional bidi markup. In the following example, the exclamation mark should appear at the end of the Arabic text, ie. to the left, like this:

Unfortunately, if we rely solely on the bidirectional algorithm we see this:

Given our understanding of the bidi algorithm we can easily understand why this happened. Because the exclamation mark was typed in between the last RTL letter 'ب' (on the left)‌ and the LTR letter 'i' (of the word 'in') its directionality is determined by the base direction of the paragraph, ie. LTR in this case.

Because the exclamation mark is seen as LTR it joins the directional run that includes the text 'in Arabic'.

Fixing use case 6 when the direction is known

The general solution mentioned above works fine: just put the opposite-direction phrase in an element with a dir attribute. If there isn't already an element present, use a span.

Fixing use case 6 for injected text

Use bdi if there isn't already a surrounding element, otherwise put a dir="auto" on the surrounding element.

Use case 7: Telephone numbers, MAC addresses, etc.

The picture below shows the expected result of displaying a telephone number in a right-to-left context, where the area code is surrounded by parentheses, and where the number appears at the beginning of a line or after some right-to-left text.

The next picture shows what you actually see, if you rely solely on the bidi algorithm.

Because these are numbers, the order applied by the bidirectional algorithm is slightly different from what we've seen before, but the fix is essentially the same.

Here is another, somewhat more problematic example of the same thing. The picture below shows a MAC address number as you would expect to see it displayed in a right-to-left context. The sequence 01:02:aa:4a:bb:06 looks exactly the same as it would in a left-to-right context.

Here, however, is what you will see when relying solely on the bidirectional algorithm.

This is particularly worrisome, since it's not obvious when the order is incorrect. Even if you did know it was incorrect, it is not at all clear how it should be read.

Although there are more characters involved, this problem is caused because the bidirectional algorithm assumes that the initial run of numbers (and colons, since they are neutral) are associated with the preceding Hebrew text, rather than part of the MAC address.

This example indicates that you should always wrap MAC addresses, and similar numbers, with directional information.

Fixing use case 7 when the direction is known

The solution is the same. Put the opposite-direction phrase in an element with a dir attribute. If there isn't already an element present, use a span. The following code would be used in an overall right-to-left context.

Fixing use case 7 for injected text

Use bdi if there isn't already a surrounding element, or put dir="auto" on a surrounding element. We just show the simplest case here. The following code would be used in an overall right-to-left context.