RTL steppers and multi-step flows
Build RTL steppers with matching step order, connectors and navigation, and handle Arabic labels, validation and conditional stages.
By Omran Khleifat, Founder of Ritla
Guide12 min read
A stepper can number its stages correctly and still tell the wrong story. The first stage sits on the right, but a connector fills from the left. Next opens the expected form, but its arrow points back toward the completed stages. On a phone, the current Arabic label disappears behind a fixed-width badge.
Treat the flow's order as application data and its direction as a presentation rule. In a horizontal Arabic sequence, the first stage belongs on the right and later stages extend leftward. A vertical sequence still proceeds from top to bottom. Neither layout requires reversing the underlying steps.
Consider an archive digitization request: select an archival collection, define the digitization scope, then review and send the request. Oversized material adds a preparation stage before review. That single branch exposes several failures that a static three-circle screenshot cannot: unstable numbering, completion attached to the wrong stage, and Back returning to a stage that no longer exists.
Preserve the workflow order in both languages#
Keep collection, scope and review in that order in the DOM and in the workflow definition. On an RTL flex row, the browser places the first item at the right. The item following it appears to its left. In English, the same normal row begins at the left.
This ordering behavior was measured in Chromium 151. Test the finished component in your supported browsers too. MDN's flex-direction reference describes how a row follows the container's direction.
The layout mistake is adding row-reverse to an already RTL stepper. That reverses the row a second time. Reversing the data array is worse: it changes which stage the application considers first. CSS order can also make the visual progression disagree with the source sequence.
Use dir="rtl" on the Arabic page or component, with a normal row for the horizontal indicator. lang="ar" identifies the language; it does not establish that layout direction. Keep any explicit LTR content inside an individual label from changing the direction of the whole step list.
Verify the sequence by reading the actual labels, not by checking whether a circle is right-aligned. Starting at the right, an Arabic reader should encounter collection before scope, then review. On a vertical layout, those same stages should appear top to bottom. A vertical stepper needs no bottom-to-top reversal.
Give the current stage a meaning beyond its color#
An ordered list communicates a sequence. If completed stages are navigable, place that list in a labeled navigation region. If the indicator is purely informational, a labeled section or group can be more appropriate than navigation.
This example is the unbranched request while the scope stage is open. Its collection URL represents an application route that must restore saved request data. The connector spans are decorative.
<nav class="archive-progress" dir="rtl" lang="ar" aria-label="مراحل طلب الرقمنة"> <ol class="archive-steps" role="list"> <li class="archive-step" data-state="complete"> <a class="archive-step__target" href="/ar/digitization/collection"> <span class="archive-step__marker" aria-hidden="true">١</span> <span>المجموعة الأرشيفية</span> <small class="archive-step__status">مكتملة</small> </a> <span class="archive-step__connector" aria-hidden="true" style="--segment-fill: 100%"><span></span></span> </li> <li class="archive-step" aria-current="step"> <span class="archive-step__target"> <span class="archive-step__marker" aria-hidden="true">٢</span> <span>نطاق الرقمنة</span> <small class="archive-step__status">المرحلة الحالية</small> </span> <span class="archive-step__connector" aria-hidden="true" style="--segment-fill: 0%"><span></span></span> </li> <li class="archive-step"> <span class="archive-step__target"> <span class="archive-step__marker" aria-hidden="true">٣</span> <span>المراجعة والإرسال</span> <small class="archive-step__status">لم تبدأ</small> </span> </li> </ol></nav>Use aria-current="step" for the one current stage in this set. It identifies the current item; it neither validates the stage nor makes it interactive. Completion has separate visible text, so a visitor does not need to distinguish two shades of the same color.
The list supplies the sequence; the decorative badges repeat its position visually. Do not make future stages disabled buttons merely to obtain circular styling. Plain text is enough when visitors cannot navigate there. A completed stage can be a link on a page-based flow or a button in a client-rendered flow, depending on what activation actually does.
Do not assign tab roles to this list just because selecting a stage replaces a panel. A sequential form has validation and progression rules that differ from a tab interface. Keep native link and button keyboard behavior unless the component deliberately implements another complete interaction pattern.
W3C's multi-page form guidance recommends showing progress and, where possible, letting people revisit completed stages while preserving their entered data. Saving is part of the navigation contract, not a side effect of changing the highlighted circle.
Anchor connectors to the sequence's inline direction#
For the markup above, start with an equal-width horizontal layout. Labels can wrap within their own cells; the connector occupies the badge row rather than running through the text.
.archive-steps { display: flex; margin: 0; padding: 0; list-style: none;}.archive-step { position: relative; flex: 1 1 0; min-inline-size: 0; padding-inline-end: 0.875rem;}.archive-step__target { display: block; color: inherit; text-align: start;}.archive-step__marker { display: grid; place-items: center; inline-size: 2.25rem; block-size: 2.25rem; border: 1px solid currentColor; box-sizing: border-box;}.archive-step__status { display: block; }Problem: physical offsets preserve an English connector even after the cells follow RTL.
.archive-step__connector { position: absolute; left: 2.75rem; right: 0.5rem; top: 1.125rem; height: 0.125rem; background: #c4c9cd;}.archive-step__connector > span { position: absolute; left: 0; top: 0; width: var(--segment-fill, 0%); height: 100%; background: #185b77;}The line is intended to start after the badge and extend toward the next cell. In Arabic, the badge is on the cell's right, while these declarations still reserve space on its left. The fill also remains anchored on the left. A fully filled line can conceal the second problem; a partially filled connector exposes it.
Better: replace those two rules with logical positioning, preserving the English geometry.
.archive-step__connector { position: absolute; inset-inline-start: 2.75rem; inset-inline-end: 0.5rem; inset-block-start: 1.125rem; block-size: 0.125rem; background: #c4c9cd;}.archive-step__connector > span { position: absolute; inset-inline-start: 0; inset-block-start: 0; inline-size: var(--segment-fill, 0%); block-size: 100%; background: #185b77;}The fill begins at inline start: right in this Arabic row, left in the English row. MDN documents that mapping for inset-inline-start. There is no need to rotate the whole indicator or flip its text.
Temporarily set the first connector's --segment-fill to 35%. In Arabic it should fill from its right edge toward the next stage on the left. Switch the component to LTR and verify the opposite. Restore the actual completion state afterward: this fixture percentage diagnoses direction, not how much work a user has done.
Separate connector progress from request completion#
Decide what a filled segment means. In this example, a filled connector marks the transition out of an accepted stage. It is not a timer, a measure of characters entered, or proof that the entire request has been submitted.
The review stage can be current while all earlier connectors are filled. That means the visitor reached review. It does not mean the archive received the request. Keep a separate submitted state that is set only after the service confirms acceptance. A failed final request must retain the review stage and its entered data.
Avoid deriving every completed badge from stepIndex < currentIndex. A visitor can return to scope after completing preparation. Scope becomes current, while preparation may still hold valid saved answers. Conversely, editing the chosen material may invalidate preparation even though the visitor previously passed it.
Track the current stage, accepted stage data, validation results and final submission independently. Then derive presentation from those facts. If connectors represent the path to the current stage rather than saved completion, document that meaning and keep the badge statuses separate.
A branched request also changes the denominator of any overall percentage. Showing a precise percentage before the product knows whether preparation is required can imply more certainty than the workflow has. A named current stage and a conditional-stage explanation may communicate progress more honestly.
Make Back and Next follow the same model#
Next advances to the next applicable stage after the current stage passes its requirements. Back returns to the previous applicable stage and should preserve entered data without requiring unfinished fields to pass validation.
For a horizontal Arabic progression, an advance arrow points left and a return arrow points right. The control's label should say what it does, such as continuing to preparation, rather than referring to a physical arrow direction. Mirror only the directional artwork; checkmarks and stage numbers do not need flipping.
Button placement is a design choice. If the English footer places Back at inline start and Next at inline end, use the same logical layout in Arabic. That puts Back on the right and Next on the left. A product using another established action layout can retain it, provided the labels, arrows, focus order and behavior remain understandable.
For an existing footer whose source order is Back then Next, this layout keeps that relationship without rearranging the DOM:
.archive-actions { display: flex; align-items: center; flex-wrap: wrap; gap: 0.875rem;}.archive-actions__next { margin-inline-start: auto; }The parent must inherit the flow's direction. Do not call a button leftButton in the application model and then make it responsible for next. Use intent names such as previousStage and continueRequest. At the final stage, replace the generic continuation label with a submission action so the user knows the next activation sends the request.
Use stable IDs when stages appear or disappear#
An oversized item inserts preparation between scope and review. Store review, not a numeric position, as the current stage. Otherwise inserting preparation at the saved review index opens the wrong form.
These helpers define the applicable sequence and its neighboring stages. They contain no locale-dependent navigation rule:
function archiveStages({ needsPreparation }) { const stages = [ { id: 'collection', label: 'المجموعة الأرشيفية' }, { id: 'scope', label: 'نطاق الرقمنة' } ]; if (needsPreparation) { stages.push({ id: 'preparation', label: 'التجهيز الخاص' }); } stages.push({ id: 'review', label: 'المراجعة والإرسال' }); return stages;} function archivePosition(state) { const stages = archiveStages(state); const index = stages.findIndex(stage => stage.id === state.currentId); if (index < 0) throw new Error('Current stage is not applicable'); return { stages, index, previousId: stages[index - 1]?.id ?? null, nextId: stages[index + 1]?.id ?? null };}The host calls these helpers with its saved needsPreparation boolean and currentId string. It localizes labels for other routes. Validation, persistence and authorization remain responsibilities of the flow controller; this neighbor calculation does not permit skipping prerequisites.
When changing the material removes the currently open preparation stage, choose a replacement before rendering. Returning to scope is a reasonable policy for this request. When changing it adds preparation while review is open, redirect to the newly required stage or identify it as blocking submission. Keeping the review ID stable does not automatically make review reachable.
Update the indicator, heading, form, next destination and total from the same applicable sequence. Do not hide an unwanted circle with CSS while leaving its stage in the controller. Test both adding and removing preparation after saving a draft, revisiting an earlier stage and restoring a bookmarked URL.
For the helpers above, these assertions distinguish content identity from display position:
const ordinaryReview = archivePosition({ needsPreparation: false, currentId: 'review'});const oversizedReview = archivePosition({ needsPreparation: true, currentId: 'review'});console.assert(ordinaryReview.index === 2);console.assert(oversizedReview.index === 3);console.assert(ordinaryReview.previousId === 'scope');console.assert(oversizedReview.previousId === 'preparation');Review retains its identity while its position and previous destination change. Run the same assertions for both locale routes; direction should not alter these results. Add controller tests separately for whether preparation has been accepted before review is reachable. Passing this calculation test alone does not establish that progression is allowed.
Commit navigation only after its save succeeds#
Treat continuing from scope as a transaction: validate the visible answers, save the intended draft revision, then commit the destination and its indicator. Keep a save failure on scope with a retry action and the entered values intact. Showing review while a rejected save still belongs to scope creates two competing versions of the request.
Prevent repeated continuation from launching competing transitions. Disabling the pending submit action is one option; also guard the handler, since duplicate requests can arise through other entry points. Keep a visible saving status, and restore the action when a recoverable error occurs.
Back navigation during a save needs an explicit policy. If it remains available, invalidate the pending transition so its eventual response cannot reopen the destination after the visitor has returned to collection. Use a request identity or draft revision to distinguish that response from the latest navigation intent. Aborting a client request does not prove the server discarded an update.
The same rule matters when a locale switch preserves the current draft. A response started on the English scope stage must not replace a newer Arabic heading or move focus into a panel that is no longer current. Apply saved data according to the draft's revision rules, and apply navigation only if the initiating transition still owns it. Test this with a deliberately delayed response, then navigate backward before it resolves.
Validate the active stage without trapping Back#
A separate form for each stage keeps validation aligned with what the visitor can see. Next can submit that form; Back can be a navigation link or a type="button" control that preserves the draft. A button inside a form needs an explicit type when it must not submit.
With one large form containing several hidden panels, visibility and validation are separate concerns. Hiding an ordinary required control does not turn it into an input of type hidden or remove its constraints. An invalid field in a concealed stage can therefore block submission without giving the user a visible place to correct it. The HTML standard's validation rules explicitly account for invalid controls that are not rendered.
If inactive stages use disabled fieldsets, account for the data consequence: their disabled controls are excluded from form submission, and controls inside the first legend are an exception to the disabling behavior. See MDN's fieldset reference. Preserve their values in the draft and build the final payload deliberately. Disabling panels is not a complete persistence strategy.
An alternative is mounting only the active stage and keeping its values in application state. Then validate every applicable stage before final acceptance, including on the server. Test the actual submitted payload after moving backward and forward; intact text on screen does not prove that every field was included.
Translate errors and stage-specific help as well as the footer controls. A successful English validation path says nothing about whether an Arabic error summary fits the current panel. Keep a failed transition on the stage that needs correction rather than advancing the indicator and leaving the old form behind.
Move focus when the form changes#
For client-rendered navigation, changing a highlight does not tell a keyboard user where the new form begins. After a successful transition and render, move focus to the new stage heading. Give that heading tabindex="-1" so it can receive programmatic focus without becoming an extra Tab stop.
This small helper accepts the heading element after the host has rendered and revealed it:
function focusArchiveStage(heading) { heading.setAttribute('tabindex', '-1'); heading.focus();}MDN's focus method reference describes programmatic focus and its scrolling options. Test that the resulting heading is visible below any sticky header. Do not suppress scrolling unless the application supplies another way to bring the focused heading into view.
On validation failure, keep the stage open and direct attention to the error summary or first invalid field according to the form's error pattern. Link summary entries to their fields. W3C's form notification guidance covers error identification and navigation.
For page-based navigation, update the document title and visible heading with the current stage. For client-rendered flows, update them after the transition succeeds, not when a save request starts. Avoid announcing a new stage while an asynchronous failure leaves the old one active.
Use the hidden attribute or an equivalent complete hiding strategy for inactive panels, and verify that component display rules do not override it. Translating a panel offscreen is not enough: keyboard users must not tab into an invisible future stage.
Switch to vertical before labels become unreadable#
Choose the horizontal-to-vertical breakpoint from the longest applicable labels, not from the English design alone. The preparation branch adds another cell, so test it before deciding that the row fits.
For this indicator, a vertical mode can retain the same markup and statuses. Add the following to the logical connector version; the threshold is an example to adjust against the actual content:
@media (max-width: 46rem) { .archive-steps { flex-direction: column; } .archive-step { flex: none; padding-inline: 3rem 0; padding-block-end: 1rem; } .archive-step__target { min-block-size: 2.25rem; } .archive-step__marker { position: absolute; inset-inline-start: 0; inset-block-start: 0; } .archive-step__connector { inset-inline-start: 1.125rem; inset-inline-end: auto; inset-block-start: 2.625rem; inset-block-end: 0.375rem; inline-size: 0.125rem; block-size: auto; } .archive-step__connector > span { inline-size: 100%; block-size: var(--segment-fill, 0%); }}The badges move to inline start, on the right in Arabic. The connecting axis becomes vertical, so its fill grows downward in both languages. Simply rotating the horizontal line would leave the old width calculation and anchoring assumptions in place.
Allow label height to determine each row's height. Ellipsizing the current label can hide the distinction between two stages. If a compact design shows only the current stage and a position summary, preserve an understandable way to review completed stages. Avoid rendering two independently maintained indicators for desktop and mobile.
At narrow widths, verify that wrapped Back and Next controls keep their source order and that a sticky action footer does not cover fields or validation text. Changing orientation must not reset the current stage, clear a draft or send focus back to the first circle.
Test transitions as well as the indicator#
Use the archive request's states as the test fixture. Inspect the first, middle and review stages in Arabic and English, with preparation both present and absent. Confirm the named current stage, displayed form and next destination agree after each transition.
| Test | Evidence to collect |
|---|---|
| First stage in RTL | Collection is rightmost; no previous-stage destination exists |
| Partially filled connector | Fill starts at the right in the horizontal Arabic layout |
| Vertical layout | Collection remains first at the top; fill extends downward |
| Invalid scope | Scope stays current and its error can be reached |
| Back from preparation | Scope reopens with the previous answers intact |
| Branch changes on review | Newly required preparation blocks submission until resolved |
| Save or submission fails | Stage, draft and announced status remain consistent |
| Reload or browser Back | Restored content identity matches the indicator |
Test Tab and Shift+Tab through revisitable stages and form controls. Future stages should not create useless focus stops. Check the one current-stage announcement, error-summary destinations and focus after a successful advance. Repeat at increased text size with the longest Arabic label and status visible together.
Inspect connector positions in both directions, including a nonzero partial fill. A completed line alone cannot reveal its fill origin. Check document-level horizontal overflow separately from label clipping: a row can fit the document while a single label is still cut off inside its cell.
Finally, edit an earlier answer that invalidates later work. Confirm completion badges, reachable destinations and final validation reflect the revised request. These transition rules need interaction testing; a visual scan of the initial stage cannot establish them.
A free Ritla scan can check for a directional icon pointing against the sequence its control advances, , and visible text-bearing elements overlapping, . If the stage labels collide at phone width, continue with RTL elements overlapping on mobile; for connector positioning, see CSS logical properties for RTL.