Timeline
ExperimentalA top-to-bottom list of events with times and an optional status.
Also known as history timeline, events, chronology
Install with npm install @tattva/ui (setup), or copy the code from the kit in Downloads.
What happened, and when
Request receivedDone
Reading 4 filesIn progress
Two of four are done.ReportUpcoming
<Timeline events={[
{ id: "1", time: "09:40", title: "Request received", state: "done" },
{ id: "2", time: "09:41", title: "Reading 4 files", state: "current" },
{ id: "3", time: "09:44", title: "Report", state: "upcoming" },
]} />When to use it
Lists events in the order they happened, each with a time, a title and an optional status. The status is shown as a marker shape and in words, so it never relies on color.
Made of: Marker · Connecting line · Time · Title · Status label · Description
Use it for
- What an agent did during a task, step by step with times.
- The history of an update or a long job, including a step that failed.
- A short log of events a person may need to check later.
Not for
- Live progress of steps that are still running: use StepTimeline.
- A flow with decisions and branches: use ProcessDiagram.
- Steps that have no times.
Do and avoid
Order placedDone
Packed and sentDone
Out for deliveryIn progress
Your order was placed and we have started to check stock in the nearest store before packingDone
The parcel left the store and is now with the courier who will bring itIn progress
Do
- Use it when the order in time matters.
- Give each time a standard date value too.
- Keep titles to a few words.
- Show the status in words as well as the marker.
Avoid
- Do not use it for steps with no time. Use a numbered list.
- Do not rely on marker color for the status.
- Do not put long text in the title.
- Do not animate the markers.
On a phone
- Events stay in one column, and the time, title and state wrap onto more lines when they do not fit.
- Nothing in it is tappable, so there are no touch targets to size. The small state labels are 12px.
Seen in products
- Our research table lists this as an ordered list with times. Only the accessibility rules have sources.
Properties
| Prop | Type | Default | Description |
|---|---|---|---|
| eventsrequired | TimelineEvent[] | none | Each event has id, time, optional dateTime, title, optional description and optional state (done, current, upcoming, failed). |
| stateLabels | Record<TimelineState, string> | English labels | Replaces the state text for localisation. |
| className | string | none | Extra classes on the list. |
"Show code under the preview gives the code for the example on the stage."
States
States this part has beyond its default look. Build each one your screen can reach. States set by a property are in the Code tab.
- done
- An event with state done shows a lime dot with a check.
- current
- An event with state current shows a dark filled centre in a ringed dot.
- upcoming
- An event with state upcoming, or no state, shows an empty ringed dot.
- failed
- An event with state failed shows a red dot with a cross.
Tokens
Change one of these and every part that uses it follows.
--lime--on-lime--danger-soft--danger-fg--border-strong
Built in
- It is a numbered list, so screen readers say how many events there are and which one you are on.
- Each time is marked up as a time, and carries the exact dateTime you give it.
- Each status is written in words. The markers and the connecting line are hidden from screen readers.
What you need to do
- Give each event a dateTime in a standard format, such as 2026-10-03T09:40, so software can read the time.
- Translate the status words with stateLabels if your product is not in English.
Built toward WCAG 2.2 AA and checked automatically; no independent audit yet. Read the accessibility guide