Chapter 13·Scripts and Layout·~8 min·
Right-to-Left Layout Mirroring
Setting dir="rtl" reverses inline progression for flexbox, grid, and table layouts. Margins, padding, positioning offsets, and text alignment mirror automatically only when authored with CSS logical properties.
Overview
Switching an interface to a right-to-left locale mirrors the page flow from right to left. Physical CSS properties such as `margin-left` and `text-align: left` remain pinned to the physical left edge. CSS logical properties and directional icon rules let one stylesheet support both directions.
Core rule
Write layout rules with CSS Logical Properties so setting dir="rtl" on the root element mirrors the UI automatically, and flip only icons that represent navigation or linear time.
Specification note: Directional navigation arrows mirror in right-to-left interfaces, but media playback icons and clockwise refresh arrows stay unmirrored by convention.
Failure mode
Physical CSS properties such as margin-left, left: 12px, and text-align: left lock components to left-to-right coordinates. When a document sets dir="rtl" for Arabic or Hebrew, flex and grid containers reverse their axis, but physical margins, borders, and absolute offsets stay pinned to the left edge. English-only visual reviews never catch this defect because physical and logical CSS produce identical output in left-to-right mode.
Right-to-left localization mirrors the entire visual interface layout, not just the text alignment. However, certain icons must never be flipped.
Business stakes & user risk
Flipping the wrong icons (such as media play buttons, clocks, or checkmarks) creates jarring, nonsensical interfaces for native Arabic and Hebrew speakers.
Rule of thumb
Use CSS logical properties (padding-inline-start). Mirror navigation arrows, but never mirror media controls or clocks.
The Novice Trap vs. Production Standard
Contrast the intuitive assumption with the architecture required for global releases.
“Either do not mirror the UI at all, or invert every icon and coordinate across the Y-axis.”
Naive approach: Physical CSS properties and blanket mirroring
<div style={{ paddingLeft: "24px" }}><PlayIcon style={{ transform: "scaleX(-1)" }} /></div>Defect:Padding remains on the wrong side in RTL, while the video play icon points backwards to the left.
Interface structure mirrors (sidebars, back arrows, progress indicators), but universal physical metaphors (play buttons, clocks) remain unmirrored.
Production standard: CSS logical properties and selective icon mirroring
<div className="ps-6"><ChevronRightIcon className="rtl:rotate-180" /><PlayIcon /></div>Benefit:Padding shifts automatically based on reading direction, the chevron points forward, and the play icon stays standard.
Cross-Functional Review Questions
Questions for product managers, designers, engineers, and testers to ask during sprint reviews.
“Has every icon in our design system been classified as directional (mirrored) or universal (unmirrored)?”
“Is the codebase free of physical left/right CSS properties in layout components?”
“Are onboarding walkthroughs and multi-step wizards tested for RTL progression order?”
“Are data tables and charts audited to ensure time axes flow right-to-left appropriately?”
Mechanism
Physical vs. flow-relative CSS layout
The Unicode Bidirectional Algorithm reorders character runs within a line, but it does not flip box-model geometry. Physical CSS properties such as margin-left, padding-right, left, and text-align: left remain anchored to the physical left and right edges of the viewport regardless of the document's writing direction.
Setting dir="rtl" on the <html> element reverses the inline progression axis of Flexbox, CSS Grid, and table columns. When stylesheets use CSS Logical Properties (margin-inline-start, padding-inline-end, inset-inline-start, border-start-start-radius, and text-align: start), the browser maps -inline-start to the left edge in LTR documents and to the right edge in RTL documents. A single stylesheet written with logical properties mirrors automatically without requiring rtlcss build transforms or [dir="rtl"] override rules.
<html dir="rtl" lang="ar">
.row {
padding-inline-start: 44px; /* was padding-left */
text-align: start; /* was left */
}
.row .chevron {
inset-inline-end: 8px; /* was right */
}Interactive demo
Guided exercises
- 1Leave the Language toggle on English and compare the two frames. Both frames render identically in LTR because `inline-start` resolves to `left` and `inline-end` resolves to `right`.
- 2Click Arabic and read the Physical CSS column. Arabic text runs right to left, but `text-align: left` pins labels to the left edge, the back arrow stays on the left, and list chevrons point outward. The four numbered markers identify each broken physical rule.
- 3Click marker 3, on the progress bar. Anchoring the fill bar with physical `left: 0` causes the progress bar to fill from left to right instead of starting at the right edge in RTL.
- 4Now read the Logical CSS column, still in Arabic. Every row, badge, progress bar, and alignment flips cleanly because `inline-start` resolves to the right edge under `dir="rtl"`, paired with `scaleX(-1)` on the navigation arrows.
- 5In the “What flips and what doesn't” table, compare the Progress bars row with the Media playback & scrubber row. Task progress bars mirror to match reading progression, whereas media playback controls and timeline scrubbers stay left-to-right.
- 6Read the last row of “The property map”. Replacing `text-align: left` with `text-align: start` aligns text to the leading edge of the active writing direction.
Language
Both frames get dir="ltr" and lang="en". The columns differ only in which CSS properties they use.
Physical CSS
left / right · padding-left / padding-right · margin-left: auto · text-align: left
Logical CSS
inset-inline-start / end · padding-inline-start / end · margin-inline-start: auto · text-align: start
What flips and what doesn't
Mirror what depicts reading direction: arrows, chevrons, linear progress. Leave clocks, media playback, and physical objects such as the search magnifier unmirrored.
| Element | Verdict | Why |
|---|---|---|
| Back / forward arrows | Flips | Forward points left in RTL, back points right. · Material bidirectionality |
| Chevrons in list rows | Flips | chevron_left and chevron_right are on Material's list of icons to mirror. A row chevron points at the row's inline end. · Material icons guide |
| Progress bars | Flips | An RTL progress bar shows 0% on the right and 100% on the left, and fills right to left. · Material bidirectionality |
| Text alignment | Flips | dir="rtl" right-aligns text by default. Where alignment is set explicitly, text-align: start and end follow the direction; left and right do not. · W3C i18n |
| Search magnifier | Doesn't flip | The handle sits bottom-right because it depicts a right hand holding the glass, and right-handedness holds in RTL countries too. · Material bidirectionality |
| Media playback & scrubber | Doesn't flip | Playback buttons and the media progress indicator follow the direction of the media, not the direction of time. · Material bidirectionality |
| Clocks, refresh, history | Doesn't flip | Clocks still turn clockwise: RTL does not mirror the circular direction of time. · Material bidirectionality |
| Camera & other non-directional icons | Doesn't flip | Icons that do not communicate direction stay unmirrored. · Material bidirectionality |
| Question mark (help icon) | Depends on script | Mirrored for Arabic and Farsi (؟ is a distinct character), but not for Hebrew, which keeps the Latin question mark. · Material icons guide |
Verdicts follow Material Design's bidirectionality guidance, its icons-in-RTL guide, and the W3C i18n guidance on document direction.
The property map
Margins, padding, borders, insets, and alignment all have logical equivalents. Each pair renders identically in LTR; under dir="rtl", inline-start and inline-end swap sides.
| Physical (LTR-only) | Logical (direction-aware) |
|---|---|
| margin-left | margin-inline-start |
| padding-right | padding-inline-end |
| left | inset-inline-start |
| border-top-left-radius | border-start-start-radius |
| text-align: left | text-align: start |
Implementation rules
- Author all spacing and alignment with CSS logical properties. Use
margin-inline-start,padding-inline-end,inset-inline-start, andtext-align: startso one stylesheet supports bothltrandrtllayouts. - Set
dirandlangon the root<html>element. Document-level directionality ensures that portals, modals, tables, and form controls inherit the active inline direction. - Apply selective icon mirroring rules. Mirror navigation arrows, chevrons, and directional progress indicators with
:dir(rtl) { transform: scaleX(-1); }. Do not mirror media playback buttons, circular clock icons, or asymmetrical brand logos. - Enforce logical CSS in continuous integration. Configure Stylelint rules to reject physical inline properties in pull requests, and write explicit
:dir(rtl)rules for physicalbox-shadowoffsets and linear gradients.
Operational context
Roles
Workflow stages
- ·RTL architecture and stylesheet audits
- ·Component library development
- ·Design handoff for Arabic and Hebrew interfaces
See it in a market: Egypt · an Arabic-script market →
Production incident
Setting dir="rtl" on an application built with physical CSS properties leaves margins, absolute offsets, text alignment, and directional chevrons anchored to their LTR positions. Ahmad Shadeed's RTL Styling 101 catalogs these failure modes across production Arabic interfaces and maps each physical rule to its flow-relative replacement.