---
title: Timeline
summary: A timeline is a list of events in order, with an icon or an avatar per event and a card for its content, for activity feeds and histories.
description: Visualize events in chronological order with a timeline. Add icons, avatars, and text to present processes and activity feeds.
related: [/ui/components/step, /ui/components/status]
source: core/scss/ui/_timeline.scss
css-vars: timeline
classnames:
  component:
    - class: timeline
      desc: Container element
  part:
    - class: timeline-event
      desc: One entry on the timeline
    - class: timeline-event-icon
      desc: Marker on the line, next to the entry
    - class: timeline-event-card
      desc: Card holding the content of the entry
  style:
    - class: timeline-simple
      desc: Drops the cards and the connecting line for a plain list
---
import Example from '@components/Example.astro';
import Icon from '@ui/Icon.astro';
import Timeline from '@shared/components/demo/Timeline.astro';

## Overview

A timeline is a list of events in order. Build it from three parts:

- `.timeline` on a `ul` element wraps the whole list.
- `.timeline-event` on each `li` holds one event and draws the line to the next one.
- `.timeline-event-icon` marks the event, and `.timeline-event-card` holds its content.

The line between events is drawn by the events themselves, so the last one never gets a trailing line.

<Example>
<ul class="timeline">
  <li class="timeline-event">
    <div class="timeline-event-icon"><Icon name="check" /></div>
    <div class="card timeline-event-card">
      <div class="card-body">
        <div class="text-secondary float-end">1 day ago</div>
        <h4>Database backup completed</h4>
        <p class="text-secondary mb-0">The nightly backup finished without errors.</p>
      </div>
    </div>
  </li>
  <li class="timeline-event">
    <div class="timeline-event-icon"><Icon name="briefcase" /></div>
    <div class="card timeline-event-card">
      <div class="card-body">
        <div class="text-secondary float-end">2 hrs ago</div>
        <h4>3 new products were added</h4>
        <p class="text-secondary mb-0">They are already visible in the catalog.</p>
      </div>
    </div>
  </li>
</ul>
</Example>

## Event icons

The icon marker is a plain box, so any [icon](/ui/components/icon) or [avatar](/ui/components/avatar) fits inside. Add a `bg-*-lt` class to tint it and tell event types apart at a glance.

<Example>
<ul class="timeline">
  <li class="timeline-event">
    <div class="timeline-event-icon bg-green-lt"><Icon name="check" /></div>
    <div class="card timeline-event-card">
      <div class="card-body">Deployment finished</div>
    </div>
  </li>
  <li class="timeline-event">
    <div class="timeline-event-icon bg-red-lt"><Icon name="alert-triangle" /></div>
    <div class="card timeline-event-card">
      <div class="card-body">Build failed on the release branch</div>
    </div>
  </li>
  <li class="timeline-event">
    <div class="timeline-event-icon">
      <span class="avatar avatar-sm" style="background-image: url(/static/avatars/000m.jpg)"></span>
    </div>
    <div class="card timeline-event-card">
      <div class="card-body">Paweł Kuna commented on the pull request</div>
    </div>
  </li>
</ul>
</Example>

## Simple timeline

Add `.timeline-simple` to hide the icons and pull the cards to the edge. Use it when the events need less decoration, for example in a narrow column.

<Example>
<Timeline simple />
</Example>

## Examples

A timeline works well as an activity feed, where each event mixes text, links and its own time.

<Example>
<Timeline />
</Example>

## Accessibility

A timeline is a list of events, so keep the list markup and let the content say what happened.

- Use `ul` and `li` elements. A screen reader then announces how many events there are and where the reader is in the list.
- Put the event time in a `time` element with a `datetime` attribute, so "2 hrs ago" also has an exact value.
- The icon is decoration on top of the text. Keep the meaning in the heading or the body of the card, never in the icon color alone.
- Keep heading levels in order. `h4` inside a card only sets the look - pick the level that fits the page outline.