A stepper drives a flow someone completes. A timeline reports events that already happened or are scheduled. If removing an event would not change what someone does next, you have a timeline.

Vertical or horizontal timeline?

Vertical is default for activity feeds and project history on web. Horizontal timelines suit short roadmaps with few milestones. Vertical scales to dozens of events with scroll.

How much detail per event?

A title, a date and one line of body copy fit most rows. Link to a detail page when the event needs paragraphs or attachments. The timeline itself should stay scannable.

Should future events look different?

Yes. Past events use muted or completed styling. The current milestone can use stronger fill. Future events stay outline or muted so the line reads as progress toward launch.

Absolute dates or relative?

Absolute dates for audits and contracts. Relative times, like 2 hours ago, for live activity feeds that update often. Some products show relative in the row and absolute in a tooltip.

Does a timeline need a connecting line?

A vertical line between dots helps the eye follow order. It is decorative for single events but valuable past three items. The dot and the date should carry meaning without the line (WCAG 1.4.1).

Timeline

A timeline lists events on a vertical axis in time order. It shows what happened, what is happening now, and what is planned next.

Structure and navigationBuild difficulty: Easy<ol>

Also called Activity timeline, Event log, History line.

Click an event to highlight it. The vertical line connects past, current and future items. Tab through the event buttons.

For designers

A timeline turns a log into a story. Order history, deployment feeds and project milestones all benefit from a line that reads downward through time. People see the latest event first or last depending on your sort, but the axis makes sequence obvious.

The cost is empty space. Each event needs a row tall enough for a dot, a date and copy. A dense table of the same data fits more rows on screen. Reach for a timeline when narrative order matters more than column count.

GitHub's deployment timeline and Stripe's event log both use the vertical line because the story is sequential. Someone asks what happened after the deploy, not what the deploy ID sorts next to in a grid.

Use a timeline when

Items have real dates or times and order matters chronologically
People scan a story of what happened, like order history or project milestones
Past, current and future events share one column but need different emphasis

Reach for something else when

The screens are steps someone must complete in order. Use a stepper instead.
The rows are peers with no time relationship. Use a list instead.
The data needs many sortable columns. Use a table instead.

Variants

Kickoff call

Design review

Launch

Past events with a soft fill, current event with a solid dot, future events muted on the line.

Past. Soft fill on the dot, normal text. Events already completed.

Current. Solid fill on the active milestone, stronger title.

Future. Outline dot, muted text. Scheduled work still ahead.

How to build a timeline

Use an ordered list when sequence matters semantically. Each item holds a date, a marker on the line, and the event content.

<ol aria-label="Order history">
  <li>
    <time datetime="2026-08-12">12 Aug</time>
    <p>Contract signed</p>
  </li>
  <li>
    <time datetime="2026-08-22">22 Aug</time>
    <p>Design review</p>
  </li>
</ol>

Use real time elements with datetime attributes so assistive tech and search engines get machine-readable dates. The visible label can stay short.

Tab order follows interactive elements inside events, not every dot on the line. If the whole event row is clickable, one button per row beats separate links on the date and the title.

Grouping by day reduces repetition. One date header for 12 August, then several events underneath without repeating the date on every row. The line still connects events, but the header gives a landmark for screen reader users jumping by heading.

Timezone labels matter for distributed teams. Show the zone once in the page header when events cross UTC, or put local time in each row with a tooltip for UTC.

Edge cases

Same-day events. Stack them with times in the label, or group under one date header.

Very long histories. Paginate or load older events on demand. A thousand-row timeline without virtual scroll freezes the page.

Live updates. New events at the top should announce politely with aria-live="polite" without moving focus away from what someone is reading.

Attachments. When an event includes a file, put the download link inside the event body. The dot on the line should not be the only clickable target for a long row.

Common questions

Timeline or stepper?: A stepper drives a flow someone completes. A timeline reports events that already happened or are scheduled. If removing an event would not change what someone does next, you have a timeline.
Vertical or horizontal timeline?: Vertical is default for activity feeds and project history on web. Horizontal timelines suit short roadmaps with few milestones. Vertical scales to dozens of events with scroll.
How much detail per event?: A title, a date and one line of body copy fit most rows. Link to a detail page when the event needs paragraphs or attachments. The timeline itself should stay scannable.
Should future events look different?: Yes. Past events use muted or completed styling. The current milestone can use stronger fill. Future events stay outline or muted so the line reads as progress toward launch.
Absolute dates or relative?: Absolute dates for audits and contracts. Relative times, like 2 hours ago, for live activity feeds that update often. Some products show relative in the row and absolute in a tooltip.
Does a timeline need a connecting line?: A vertical line between dots helps the eye follow order. It is decorative for single events but valuable past three items. The dot and the date should carry meaning without the line (WCAG 1.4.1).

Last reviewed 26 AUG 2026