RTL progress indicators
Choose the direction for RTL task bars, media timelines and progress rings, and keep animation, percentages and accessible values consistent.
By Omran Khleifat, Founder of Ritla
Guide13 min read
An Arabic download panel can show the correct percentage while its bar grows from the wrong edge. Setting dir="rtl" changes the surrounding layout, but a custom fill anchored with left: 0 keeps its English origin. Mirroring the whole panel repairs the picture at the cost of reversing its text and controls.
For ordinary task completion, let a horizontal bar grow from inline start: right in Arabic, left in English. Keep the completed amount unchanged. A task that is partly complete does not become mostly complete because the interface changed language.
That recommendation does not cover every object called a progress indicator. Media timelines can retain an LTR playback convention, circular indicators can keep their rotation direction, and an unknown-duration loader should not invent a percentage. Decide what the indicator measures before changing its drawing.
Choose direction from the indicator's meaning#
Use an offline city map pack as the working example. The application is preparing map tiles for a district, then checking that the pack can be opened offline. This is task progress, separate from the map's geographical orientation.
| Indicator | Direction decision in an Arabic interface |
|---|---|
| Horizontal map-preparation bar | Grow from the right toward the left |
| Ordered preparation stages | Keep stage order; lay a horizontal sequence out from the right |
| Vertical task bar | Define its growth axis explicitly; do not infer it from horizontal mirroring |
| Circular completion ring | Follow the component system's established sweep direction |
| Busy spinner with no known total | Keep its established rotation; show activity without a numeric claim |
| Audio or video timeline | Follow the player convention, which can remain LTR |
Material's bidirectionality guidance explicitly exempts media playback progress and clockwise circular indicators from blanket mirroring. Treat that as a design-system convention, not an HTML rule that forces every custom player to behave identically.
Keep the map itself geographically consistent. The progress bar can fill leftward while north remains where the map places it. A visual component's location in an RTL panel does not mean its internal coordinate system should reverse.
Document the expected origin for each indicator variant. “Mirror progress” is too broad for a component library that serves downloads, media, dashboards and loading buttons. Separate the task-progress variant from the playback variant so a global RTL selector cannot silently change both.
Start with a labeled native progress element#
When the browser's presentation suits the product, use the native element. Here, preparing 86 of 215 tiles means the measured work is 40% complete:
<section dir="rtl" lang="ar"> <h2>خريطة حي المنارة</h2> <label for="native-map-progress">تجهيز الخريطة للاستخدام دون اتصال</label> <progress id="native-map-progress" value="86" max="215"></progress> <p>تم تجهيز ٨٦ من ٢١٥ مقطعًا</p></section>The HTML progress element represents task completion, supplies progress semantics, and accepts a positive maximum with a value between zero and that maximum. Its minimum is zero. The associated label names the task; text placed between the progress tags is not a substitute for that label.
For horizontal writing, the HTML rendering guidance describes an RTL progress bar with its start on the right. Let direction reach the element, then inspect the actual native presentation in supported browsers and operating systems. Platform appearance and custom theme rules still need testing.
Do not apply an extra scaleX(-1) because the containing page is Arabic. First verify whether the native control already follows its direction. A second mirror can undo the behavior you wanted.
Use a progress element for an ongoing task, rather than a gauge of an existing condition. Storage occupancy, for example, is a measurement rather than the progress of preparing the map. That distinction affects semantics even if both designs contain a colored horizontal track.
Anchor a custom fill at inline start#
If the design needs a custom track, keep the task label and visible count outside the progressbar element. This is an alternative to the native example, showing the same map preparation:
<section dir="rtl" lang="ar"> <h2>خريطة حي المنارة</h2> <p id="map-progress-label">تجهيز الخريطة للاستخدام دون اتصال</p> <div id="map-progress" class="map-progress" role="progressbar" aria-labelledby="map-progress-label" aria-valuemin="0" aria-valuemax="215" aria-valuenow="86"> <div class="map-progress__fill" aria-hidden="true" style="--completion: 40%"></div> </div> <p id="map-count">تم تجهيز ٨٦ من ٢١٥ مقطعًا</p> <bdi id="map-percent" aria-hidden="true">٤٠٪</bdi></section>The shared track dimensions are deliberately simple:
.map-progress { position: relative; inline-size: 100%; block-size: 0.625rem; overflow: hidden; background: #cbd4d9;}Problem: a physical anchor survives the language change.
.map-progress__fill { position: absolute; left: 0; top: 0; width: var(--completion, 0%); height: 100%; background: #225e76;}The fill occupies the correct fraction but stays attached to the left edge. Translating its label or right-aligning the count cannot change that anchor.
Better: replace the fill rule with logical positioning and sizing.
.map-progress__fill { position: absolute; inset-inline-start: 0; inset-block-start: 0; inline-size: var(--completion, 0%); block-size: 100%; background: #225e76; transition: inline-size 180ms linear;}The English layout retains its left origin. In the Arabic layout, the origin becomes the right edge. Logical inline sizing expresses the axis; the start anchor determines which edge stays fixed as the value grows. See CSS logical properties for RTL for the property mapping.
Set the fixture to an empty value, a visibly partial value and a full value. At full completion, either origin looks identical, so a finished-bar screenshot cannot establish that the direction is correct. Inspect the partial state before adding animation.
Update drawing and semantics from one fraction#
A custom bar has several representations of the same fact: the fill size, accessible numeric value, visible count and percentage. Compute them together. Otherwise a separately rounded counter can disagree with the track or an old aria-valuenow can survive a visual update.
This renderer updates the custom example above. The job controller calls it with measured completed and total tile counts; it is not a timer that estimates backend work:
const mapCountFormat = new Intl.NumberFormat('ar', { numberingSystem: 'arab'});const mapPercentFormat = new Intl.NumberFormat('ar', { style: 'percent', numberingSystem: 'arab', maximumFractionDigits: 0}); function mapFraction(completed, total) { if (!Number.isFinite(completed) || !Number.isFinite(total) || total <= 0 || completed < 0 || completed > total) { throw new RangeError('Invalid map progress counts'); } return completed / total;} function renderMapProgress(completed, total) { const fraction = mapFraction(completed, total); const bar = document.getElementById('map-progress'); const fill = bar.querySelector('.map-progress__fill'); const countText = `تم تجهيز ${mapCountFormat.format(completed)} من ${mapCountFormat.format(total)} مقطعًا`; fill.style.setProperty('--completion', `${fraction * 100}%`); bar.setAttribute('aria-valuemax', String(total)); bar.setAttribute('aria-valuenow', String(completed)); bar.setAttribute('aria-valuetext', countText); document.getElementById('map-count').textContent = countText; document.getElementById('map-percent').textContent = mapPercentFormat.format(fraction);} renderMapProgress(86, 215);The numeric attributes retain machine-readable decimal numbers. Localized digits belong in human-readable text. Intl.NumberFormat supplies the locale's percent formatting; its percent formatter takes a fraction, so passing the already multiplied percentage would inflate the result.
The helper rejects invalid measurements rather than silently turning a negative total or an excessive completed count into a plausible bar. Report that producer error through the application's error handling. Unknown totals are a different state, covered below.
Rounding introduces another boundary to test. At 214 of 215 tiles, whole-percent rounding produces 100% even though one tile remains. That does not make the measured fraction equal to one. Keep readiness tied to the job's accepted state, and retain the exact count when the rounded percentage would otherwise conceal remaining work. If the product reserves a full percentage label for confirmed completion, implement that display policy explicitly rather than letting the formatter decide whether the map is ready.
Keep the percentage as one formatted value, with its associated punctuation, rather than moving the percent sign manually for Arabic. The visible percentage is decorative here because the progressbar has the measured count as its value text. For surrounding mixed-direction labels, use numbers inside RTL text instead of changing the track direction to repair text ordering.
A scaled fill needs its own origin rule#
Some implementations use a full-width fill and animate scaleX() instead of its inline size. Setting dir does not turn a physical transform origin into a logical one. Scaling around the center also makes a bar expand in two directions.
If you choose scaling, replace the width-based fill implementation rather than stacking the two techniques. The renderer must then write the fraction to --ratio instead of writing a percentage to --completion:
.map-progress__fill { position: absolute; inset: 0; background: #225e76; transform: scaleX(var(--ratio, 0)); transform-origin: left center; transition: transform 180ms linear;}.map-progress__fill:dir(rtl) { transform-origin: right center;}Here, physical left and right are explicit counterparts. MDN's transform-origin reference defines those physical keywords. Do not assume that every direction-sensitive property has a logical keyword replacement.
Keep the text outside the scaled element so it retains its proportions. A border or rounded end drawn inside that element will also be scaled; inspect it at small fractions before choosing this technique. There is no universal need to use transforms for a small task bar. Pick the implementation that meets the design and measure performance if updates create a problem.
The :dir(rtl) selector requires semantic HTML direction. CSS-only direction: rtl does not make it match, as measured in Chromium 151. Use dir on the page or component and test a live locale switch while the bar is partly complete.
Unknown progress is not zero progress#
While the map service discovers the required tiles, the application may know that work is running without knowing the total. A value of zero means a known task has completed none of its work. Indeterminate progress means the completion fraction is unavailable.
For a native progress element, remove its value attribute to enter the indeterminate state. For a custom progressbar, omit aria-valuenow. Remove stale value text and a stale visible percentage when changing modes. These rules are described in the native progress reference and the ARIA progressbar reference.
Use a task-specific message while discovering the map's size. When a reliable total arrives, switch to determinate progress using the completed work already reported. Do not reset to zero simply because the presentation changed from a spinner to a bar.
Avoid a timer that keeps increasing toward completion regardless of the job. It can imply that a stalled request is advancing and leaves the interface unable to explain a long final pause. If the denominator changes because additional tiles are discovered, either keep discovery as its own phase or explain that the estimate changed. Do not conceal it by falsifying the completed count.
An indeterminate linear sweep can follow the component's chosen RTL motion, but its moving segment does not represent an amount. Test its entrance and exit separately from determinate fill growth. Removing a transform sign from a sweep without checking its clipping can leave the segment travelling outside the visible track for part of its cycle.
Keep circular progress independent of text direction#
A ring has a start angle, a sweep direction and a completed arc length. Those are drawing decisions, not consequences of the direction of adjacent Arabic text. Material's progress indicator guidance uses clockwise circular indicators; retain that convention if your component system follows it.
This SVG is a visual alternative to the custom bar's fill. It belongs inside an appropriately labeled progressbar wrapper, with the count and any controls outside that wrapper. Size that wrapper for the ring instead of retaining the linear track's short height and clipping. Do not render it as a second separately announced progress indicator for the same task.
<svg class="map-ring" viewBox="0 0 64 64" width="64" height="64" aria-hidden="true" focusable="false"> <circle cx="32" cy="32" r="26" fill="none" stroke="#cbd4d9" stroke-width="5" /> <circle class="map-ring__value" cx="32" cy="32" r="26" fill="none" stroke="#225e76" stroke-width="5" pathLength="100" stroke-dasharray="100 100" stroke-dashoffset="60" transform="rotate(-90 32 32)" /></svg>The pathLength attribute normalizes stroke-distance calculations. With a normalized length of 100, this ring's offset is 100 * (1 - fraction), giving 60 for the map's current fraction. Use numeric dash values here; a dash-offset percentage is not a percentage of the circle's circumference. See stroke-dashoffset for its units.
The rotation places the start at the top. SVG circle geometry follows its defined path, described in SVG's basic shapes specification; dir="rtl" does not redraw that path. Test a small nonzero arc to verify its starting point and sweep. An empty or complete ring cannot reveal those choices.
Animate changes to the dash offset if the design needs interpolation. Do not spin a determinate arc around the circle merely to show that work continues: that makes its stable starting point disappear. An indeterminate spinner can rotate, but it should not retain a determinate numeric value.
Inspect the stroke's end caps if a theme changes them. Rounded caps extend the visible ends of an arc and can make a tiny amount look larger than its normalized length. At zero, explicitly hide a residual dot if the chosen styling produces one. Verify the terminal state separately so a seam or cap does not suggest that a fully completed ring still has work remaining.
Preserve playback conventions without forcing Arabic text LTR#
If the map panel includes a tutorial video, its preparation bar and its playback timeline can point in different directions for different reasons. The task bar measures completed preparation; the player timeline represents a position in media using its established control convention.
Scope any LTR exception to the timeline or player control component that needs it. Keep the Arabic title, transcript and explanatory text in their own appropriate direction. Forcing the whole panel LTR to preserve playback also changes the task bar's inherited direction.
A read-only playback indicator is also different from an interactive seek control. Adding role="progressbar" to something users drag does not supply slider keyboard behavior or an accessible way to change its value. Use the player framework's documented controls and verify its keyboard and pointer behavior in the Arabic route.
Test the current-time label, remaining-time label, track endpoints and actual seek destination together. Flipping only the elapsed fill can leave the handle, buffered region and pointer-to-time calculation inconsistent. A mirrored screenshot cannot prove that selecting a point reaches the intended media position.
Announce job changes without announcing every frame#
The ARIA progressbar definition makes progress read-only. It does not need a Tab stop just to expose its changing value. Keep Pause, Cancel and Retry as separate controls with their own labels and keyboard focus.
Progressbar descendants have presentational semantics, so do not put the task heading or an interactive Cancel control inside the element carrying that role. The custom example keeps its semantic content outside and uses aria-labelledby to provide the name.
Use a separate polite status message for changes such as preparing, paused, failed and ready offline. Avoid making the entire fast-updating count a live region. W3C's status-message guidance explains how to expose updates without requiring focus to move to them.
If a content region is being updated, aria-busy can describe that region's incomplete update. Do not mark the entire application busy, and keep the status announcement outside a busy region if it must be delivered during that update. Clear the busy state when the update finishes or fails.
Preserve focus on the action the visitor is using. A background progress update must not steal it. On completion, make the map-opening action available and announce readiness; do not automatically activate it or move focus away from unrelated work.
Separate completion, motion and failure states#
Preparing every tile does not prove that the offline pack is usable. If verification still follows, label the tile bar as tile preparation and show verification separately, or define an overall measure that includes both. An unlabeled full bar beside a continuing spinner leaves the visitor guessing whether the task succeeded.
A segmented indicator can show discovery, downloading and verification as named stages. Keep their source order intact and let a normal horizontal row inherit RTL; a vertical version can retain the same top-to-bottom order. Its current stage describes where the job is working, while completed stages describe accepted results. Reaching verification is not the same as completing verification.
Do not assign each stage an equal share of an overall percentage merely because the design draws equal segments. Discovery and verification may have no measured completion fraction, while downloading has tile or byte counts. Show the named phase with its available measurement, or use a defined weighting model supported by the job system. State whether progress counts tiles or transferred bytes: differently sized tiles can make those fractions diverge without either measurement being reversed.
Track paused, cancelled and failed states independently from the measured fraction. Pause should stop activity animation while retaining the accepted completed count. Failure should show a reason and an available recovery action rather than leaving an endlessly moving segment. A retry needs a defined policy for retained tiles and job identity.
Ignore late progress events from a cancelled or replaced job. Otherwise a new map download can inherit the previous job's fraction or a failed job can return to a running appearance. Test delayed messages after Retry, navigation away and a locale switch.
Respect prefers-reduced-motion by removing unnecessary interpolation and repeating motion. Keep the task state and measured value visible:
@media (prefers-reduced-motion: reduce) { .map-progress__fill, .map-ring__value { transition: none; animation: none; }}This applies to the custom components. Native controls may use platform-specific animation, so test their actual presentation too. A stationary unknown-progress indicator still needs text that distinguishes ongoing work from a paused or failed task.
Test direction before testing the finished state#
Build a fixture that can hold the job at empty, partial, nearly complete and complete values. Add unknown-total, paused, failed and ready states. Compare the actual fill edge with the reported count and accessible value rather than checking each representation in isolation.
Before inspecting pixels, exercise the numeric contract with a fixed total. mapFraction(0, 215) must return zero, the working example must return 0.4, and mapFraction(215, 215) must return one. A zero total, a negative count and a completed count above the total must take the error path. Test unknown mode through its separate state transition rather than passing an invented total to this helper. These checks distinguish incorrect measurements from a drawing that merely starts at the wrong edge.
For the custom linear bar, measure the track and fill bounds after transitions settle. In RTL, their right edges should coincide while the fill's left edge moves as completion increases. In LTR, their left edges should coincide. Use a small tolerance for fractional pixels; do not require identical integer coordinates after browser zoom.
For the ring, inspect an early arc and a later arc with both direction attributes. Verify the same chosen start and sweep, and confirm the amount still matches the job. For a media variant, test its own playback contract rather than reusing the task-bar expectation.
Repeat at narrow widths, increased text size and reduced motion. The Arabic task name and count should wrap without overlapping the track or its action controls. Keep percentage text outside a tiny fill: early progress should not make its label unreadable merely because the colored region is narrow.
Finally, change locale during a partial update, switch from unknown to known totals, and deliver a stale event after cancellation. Direction changes must not reset the numeric amount, and job lifecycle changes must not leave an old accessible value behind. These state transitions require interaction tests in addition to visual inspection.
A free Ritla scan can check for direction-sensitive physical properties without an RTL override, , and visible text-bearing elements overlapping, . For a fill anchored at the wrong edge, continue with physical versus logical CSS; for deciding which indicator variants should change direction, see what to mirror in RTL.