UIDex
Reference guide

The RTL guide to UI elements

When a page flips right-to-left, not everything flips with it. The hard part is not switching on dir="rtl". It is knowing what should mirror, what looks broken the moment you mirror it, and which logical CSS property removes the problem at the root instead of making you write two rules for every component. This is that reference, in one place.

From physical to logical properties

Most broken Arabic layouts trace back to a single property written as a side instead of a direction. This table is the direct substitution: write the middle column, and stop needing a separate rule per direction.

Do not writeWrite this insteadWhy
margin-left / margin-rightmargin-inline-start / margin-inline-endThe single biggest cause of a broken Arabic layout. One rule then serves both directions.
padding-left / padding-rightpadding-inline-start / padding-inline-endInner spacing for buttons and fields that carry an icon on one side.
left / rightinset-inline-start / inset-inline-endPositions of floating things: toasts, floating buttons, popovers.
text-align: left / righttext-align: start / endLets text follow the content direction instead of being pinned to one side.
border-left / border-rightborder-inline-start / border-inline-endThe coloured edge on alerts and blockquotes. It moves to the correct side on its own.
border-radius: a b c dborder-start-start-radius …Matters for joined buttons and input groups, where only the outer corners are rounded.
transform: translateX(100%)translateX(calc(100% * var(--dir)))Transforms have no logical equivalent, so define a direction variable and multiply by it.
transform-origin: lefttransform-origin: inline-startProgress bars and toast timers that drain along the reading direction.
float: leftfloat: inline-startImages wrapped by text inside articles.
background-position: leftbackground-position-x + [dir]No logical equivalent, so you need an explicit rule inside [dir="rtl"].

What mirrors, and what must never mirror

Flipping every icon with scaleX(-1) is a common mistake that produces an uncanny interface: a backwards clock, a backwards camera. The rule: mirror anything that indicates reading order or sequence, and leave anything that depicts a physical object or follows a global convention.

Mirrors

  • Directional arrows: next and previous, back, undo, and "see more".
  • Alignment and indent icons, and list icons that show text lines.
  • Progress bars and sliders, which start from the right.
  • Button order in a dialog footer.
  • Skeleton shimmer direction and slide-in animations.

Never mirrors

  • Clocks, timers, and anything showing hands. Time does not mirror.
  • The loading spinner, whose rotation is not a reading direction.
  • Status icons: check, error, warning, info.
  • Icons of real objects: keys, locks, cameras, shopping carts.
  • Logos, and any icon containing a Latin letter or a digit.
  • Media play buttons ▶, a global convention that ignores language direction.
  • The downward chevron on a dropdown, which is vertical, not horizontal.

Bidirectional text (Bidi)

The hardest Arabic bugs are not layout bugs. They live in the single line that mixes Arabic, Latin and digits. The browser's bidi algorithm runs automatically, and in a handful of recurring cases it gets the result wrong.

Numbers and IDs inside Arabic text

Numbers run left-to-right even inside an Arabic sentence. Trouble starts when they sit next to #, %, + or -, which can jump to the wrong end. Wrap them in <bdi> or a span with unicode-bidi: isolate.

Code identifiers inside an Arabic sentence

A token like aria-expanded or max-width: 100% at the end of an Arabic sentence can have its hyphen or colon displaced. Any Latin run inside Arabic text must be direction-isolated.

User-generated content

Never assume the language of a comment or a filename typed by a user. Put dir="auto" on the input and on the place it is displayed, and let the browser decide from the first strongly-directional character.

Fonts and line height

Arabic letterforms are taller and more connected than Latin ones, so a line height tuned on English feels cramped in Arabic. Raise line-height by roughly 0.15 to 0.25 for Arabic text, and drop letter-spacing entirely, because it breaks the joins between letters.

RTL notes per element

219

Every element page in the dictionary carries its own RTL section. This is a fast index of every note published so far.