Timeline
Events in order: transfer tracking, order status, account activity, audit logs. Each item has an indicator, a connector and short content.
Ritla scan of this preview: 41 of 41 checks3 breakpointsScanned
Preview
Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.
Installation
Add the component
npx ritla add timelineAlso works with shadcn:
npx shadcn@latest add @ritla/timelineDependencies it brings
@phosphor-icons/reactOr copy by hand
Installing by hand copies the component's source into your project. The source comes with a Ritla UI license, so the CLI is the short way to the same files.
Usage
import { Timeline, TimelineItem } from "@/components/ui/timeline";<Timeline> <TimelineItem time="24 Sep, 10:42" title="Transfer submitted" description="Reference FT26270X482" /> <TimelineItem status="current" time="In progress" title="Sent to beneficiary bank" /> <TimelineItem status="upcoming" time="Expected by 11:45" title="Credited to account" /></Timeline>Examples
Horizontal on wide screens
layout="auto": vertical on phones, horizontal from md. Horizontal only for four steps or fewer; it runs right to left in Arabic.
Account activity
Every event is done, so every item is Complete. One line per event, and a link to the full record instead of long text.
API reference
Timeline
| Prop | Type | Default | Description |
|---|---|---|---|
layout | "vertical" | "horizontal" | "auto" | "vertical" | Figma's Layout. auto is vertical on phones and horizontal from md. |
children | TimelineItem[] | None | The items, oldest first. |
TimelineItem
| Prop | Type | Default | Description |
|---|---|---|---|
status | "complete" | "current" | "upcoming" | "complete" | Figma's Status. |
title | ReactNode | None | Figma's Title: what happened, in one line. |
time | ReactNode | None | Figma's Show time: the time or status above the title. |
dateTime | string | None | An ISO date that makes the time a <time> element. |
description | ReactNode | None | Figma's Show description: a line of detail, or a link. |
connector | boolean | true | Figma's Show connector. The last item never has one. |
statusLabel | string | None | The status for screen readers. Default: Complete, In progress, Upcoming, in the page's language. |
Usage guidelines
A timeline shows events in time order. Vertical or horizontal, statuses, how it runs in Arabic, and the checks before handoff.
1. Vertical or horizontal
Vertical fits lists and detail pages; horizontal fits a short process shown in a card, up to five items.
Do
- Use vertical by default.
- Use horizontal only when all items fit without scrolling.
Don't
- Scroll a horizontal timeline.
- Wrap horizontal items to two rows.
2. Statuses
Complete is filled, Current is the brand ring, Upcoming is outlined. Only one item is Current.
Do
- Put the time on every item.
- Use the status colour on the dot only.
Don't
- Colour the whole item by status.
- Mark a future item Complete to look done.
3. Arabic and RTL
Vertical timelines keep the rail on the inline start; horizontal ones run right to left. Dates use the app's numerals and calendar.
Before handoff
- Both layouts placed in both directions.
- All three statuses present.
- Show more behaviour decided for long lists.
Accessibility
Keyboard
Keys are written for left-to-right. In right-to-left the arrow keys swap: the one pointing toward the reading direction moves forward.
| Key | Action |
|---|---|
| Tab | To links inside items only; the timeline itself isn't a control. |
ARIA
- An ordered list (
ol), so screen readers say how many steps there are and where each sits. - Indicators are hidden from it; the status is said as a word before the title. The current step is
aria-current="step". - With
dateTime, the time is a machine-readable<time>.
Arabic and RTL notes
Mirrors
- The rail and indicators sit on the right in vertical timelines.
- Horizontal timelines run right to left; the content's end space is on the left.
Does not mirror
- The check mark doesn't mirror.
- References, numbers and phones stay left to right (
<bdi dir="ltr">).
- Numerals
- Times and numbers follow the numerals setting:
toNumeralsfor fixed strings,formatNumberfor amounts. - Arabic typography
- Time
label-12, titlelabel-14Semibold, detaillabel-14. - Mixed-direction text
- Each line is
dir="auto", so an Arabic line starts with an Arabic word as Figma asks, and a Latin reference doesn't flip the sentence.
Do
- The RTL variant for both layouts.
- Show Hijri dates where the product uses them.
Don't
- Mirror the status icons.
- Mix calendars in one timeline.
Checks it passes
The Ritla checks this component satisfies by construction. Used as documented, it does not bring these defects onto your page.
- Clipped text: content wider than its box with overflow hidden and no ellipsis
- Fixed-pixel-width container whose Arabic text exceeds the space
- Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
- letter-spacing applied to Arabic text (breaks the connected script)