Skip to main content
On this page

Timeline

Show a series of events or steps in chronological order.

When to use​

  • To display a sequence of events in chronological order, for example a customer's account activity or the steps in a completed process
  • To show the progress of a multi-step task where each step is discrete and has already happened
  • When the time or sequence relationship between events is meaningful to the user

When not to use​

  • For future steps in an incomplete process - if the user has not yet completed the steps, use a progress indicator or stepper pattern instead.
  • For navigation - a Timeline is a display component, not a navigation component. Use Tabs or page structure for navigable sections.
  • For a simple list without meaningful sequence - use a List instead.

Anatomy​

  1. Separator
  2. Node
  3. Content

Basic usage​

Loading...
Edit live code
<Timeline>
    <TimelineItem>
        <P><Strong>12 Jul 2023</Strong><br />You told us that you're moving out</P>
    </TimelineItem>
    <TimelineItem>
        <P><Strong>20 Jul 2023</Strong><br />Your moving day</P>
    </TimelineItem>
    <TimelineItem>
        <P><Strong>20 Jul 2023</Strong><br />Submit your final meter readings</P>
    </TimelineItem>
</Timeline>

Variants and features​

Custom node​

By default each item uses a TimelineDot, a solid circle in colors.border. Replace it with any element using the node prop.

Custom nodes must have a background colour and position: relative so they appear in front of the separator line. All nodes in a timeline must be the same width to keep the content column visually aligned.

Loading...
Edit live code
<Timeline>
    <TimelineItem node={
        <Icon name="electricity" size="2em" style={{
            position: 'relative',
            background: 'gold',
            padding: 4,
            borderRadius: 4
        }}/>
    }>
        <P>Electricity supply connected</P>
    </TimelineItem>
    <TimelineItem node={
        <Icon name="gas" size="2em" style={{
            position: 'relative',
            background: 'deepskyblue',
            padding: 4,
            borderRadius: 4
        }}/>
    }>
        <P>Gas supply connected</P>
    </TimelineItem>
</Timeline>

Custom separator​

By default each item uses a TimelineSeparator, a vertical line in colors.borderMuted. The separator on the last item is hidden automatically. Replace it using the separator prop.

When customising a separator, extend the default TimelineSeparator with a style override rather than replacing it entirely. This preserves the base positioning and last-item hiding behaviour.

The separator is a filled block, so override background rather than a border. Here the completed steps use a stronger colour than the default colors.borderMuted:

Loading...
Edit live code
<Timeline>
    <TimelineItem separator={<TimelineSeparator style={{ background: '#07883F' }} />}>
        <P>Move-out date confirmed</P>
    </TimelineItem>
    <TimelineItem separator={<TimelineSeparator style={{ background: '#07883F' }} />}>
        <P>Final meter readings submitted</P>
    </TimelineItem>
    <TimelineItem>
        <P>Final bill issued</P>
    </TimelineItem>
</Timeline>