Timeline

Display events in chronological order with alternating or vertical layouts.

Import

import { Timeline } from 'asterui'

Examples

Basic Timeline

Simple timeline with alternating content.

1984
First Macintosh computer
iMac
1998

import { Timeline } from 'asterui'
import { CheckCircleIcon } from '@aster-ui/icons/solid'

function App() {
  return (
      <Timeline>
        <Timeline.Item start="1984" icon={<CheckCircleIcon />} end="First Macintosh computer" endBox />
        <Timeline.Item start="iMac" icon={<CheckCircleIcon />} end="1998" startBox />
      </Timeline>
    )
}

export default App

Vertical Timeline

Stack items vertically.

Apple Watch
2015
2015
2017
iPhone X
Apple Silicon M1
2020
2020

import { Timeline } from 'asterui'
import { CheckCircleIcon } from '@aster-ui/icons/solid'

function App() {
  return (
      <Timeline vertical>
        <Timeline.Item start="2015" icon={<CheckCircleIcon className="text-primary" />} end="Apple Watch" endBox />
        <Timeline.Item start="2017" icon={<CheckCircleIcon className="text-primary" />} end="iPhone X" endBox />
        <Timeline.Item start="2020" icon={<CheckCircleIcon className="text-primary" />} end="Apple Silicon M1" endBox />
      </Timeline>
    )
}

export default App

Horizontal Timeline

Display items horizontally.

Step 1
Planning
Step 2
Development
Step 3
Testing
Step 4
Launch

import { Timeline } from 'asterui'
import { CheckCircleIcon, ClockIcon } from '@aster-ui/icons/solid'

function App() {
  return (
      <Timeline horizontal>
        <Timeline.Item start="Step 1" icon={<CheckCircleIcon />} end="Planning" endBox />
        <Timeline.Item start="Step 2" icon={<CheckCircleIcon />} end="Development" endBox />
        <Timeline.Item start="Step 3" icon={<ClockIcon />} end="Testing" endBox />
        <Timeline.Item start="Step 4" icon={<ClockIcon />} end="Launch" endBox />
      </Timeline>
    )
}

export default App

Compact Timeline

All content on one side.

1984
First Macintosh computer
1998
iMac

import { Timeline } from 'asterui'
import { CheckCircleIcon } from '@aster-ui/icons/solid'

function App() {
  return (
      <Timeline vertical compact>
        <Timeline.Item
          icon={<CheckCircleIcon />}
          end={
            <div>
              <time>1984</time>
              <div className="text-lg font-black">First Macintosh computer</div>
            </div>
          }
          endBox
        />
        <Timeline.Item
          icon={<CheckCircleIcon />}
          end={
            <div>
              <time>1998</time>
              <div className="text-lg font-black">iMac</div>
            </div>
          }
          endBox
        />
      </Timeline>
    )
}

export default App

Snap Icon

Snap icons to the start instead of center.

Project Started
2023
2023
2024
Beta Release
Public Launch
2025
2025

import { Timeline } from 'asterui'
import { CheckCircleIcon, ClockIcon } from '@aster-ui/icons/solid'

function App() {
  return (
      <Timeline vertical snapIcon>
        <Timeline.Item start="2023" icon={<CheckCircleIcon />} end="Project Started" endBox />
        <Timeline.Item start="2024" icon={<CheckCircleIcon />} end="Beta Release" endBox />
        <Timeline.Item start="2025" icon={<ClockIcon />} end="Public Launch" endBox />
      </Timeline>
    )
}

export default App

Colors

Apply different colors to timeline items.

Task 1
Completed
Completed
In Progress
Task 2
Task 3
Warning
Warning
Error
Task 4

import { Timeline } from 'asterui'
import { CheckCircleIcon, ClockIcon, ExclamationCircleIcon } from '@aster-ui/icons/solid'

function App() {
  return (
      <Timeline vertical>
        <Timeline.Item start="Completed" icon={<CheckCircleIcon />} end="Task 1" endBox color="success" />
        <Timeline.Item start="In Progress" icon={<ClockIcon />} end="Task 2" endBox color="info" />
        <Timeline.Item start="Warning" icon={<ExclamationCircleIcon />} end="Task 3" endBox color="warning" />
        <Timeline.Item start="Error" icon={<ExclamationCircleIcon />} end="Task 4" endBox color="error" />
      </Timeline>
    )
}

export default App

Mode: Start

All items aligned to start.

2020
Event One
2021
Event Two
2022
Event Three

import { Timeline } from 'asterui'
import { CheckCircleIcon } from '@aster-ui/icons/solid'

function App() {
  return (
      <Timeline vertical mode="start">
        <Timeline.Item start="2020" icon={<CheckCircleIcon />} end="Event One" endBox />
        <Timeline.Item start="2021" icon={<CheckCircleIcon />} end="Event Two" endBox />
        <Timeline.Item start="2022" icon={<CheckCircleIcon />} end="Event Three" endBox />
      </Timeline>
    )
}

export default App

Mode: End

All items aligned to end.

Event One
2020
2020
Event Two
2021
2021
Event Three
2022
2022

import { Timeline } from 'asterui'
import { CheckCircleIcon } from '@aster-ui/icons/solid'

function App() {
  return (
      <Timeline vertical mode="end">
        <Timeline.Item start="2020" icon={<CheckCircleIcon />} end="Event One" endBox />
        <Timeline.Item start="2021" icon={<CheckCircleIcon />} end="Event Two" endBox />
        <Timeline.Item start="2022" icon={<CheckCircleIcon />} end="Event Three" endBox />
      </Timeline>
    )
}

export default App

Pending State

Show an ongoing activity at the end.

Meeting started
9:00 AM
9:00 AM
9:30 AM
Presentation complete
Q&A session
10:00 AM
10:00 AM
Loading
Recording in progress...

import { Timeline } from 'asterui'
import { CheckCircleIcon } from '@aster-ui/icons/solid'

function App() {
  return (
      <Timeline vertical pending="Recording in progress...">
        <Timeline.Item start="9:00 AM" icon={<CheckCircleIcon />} end="Meeting started" endBox color="success" />
        <Timeline.Item start="9:30 AM" icon={<CheckCircleIcon />} end="Presentation complete" endBox color="success" />
        <Timeline.Item start="10:00 AM" icon={<CheckCircleIcon />} end="Q&A session" endBox color="success" />
      </Timeline>
    )
}

export default App

Loading State

Show loading spinner on individual items.

Complete
Step 1
Step 1
Step 2
Loading
Processing...
Pending
Step 3
Step 3

import { Timeline } from 'asterui'
import { CheckCircleIcon, ClockIcon } from '@aster-ui/icons/solid'

function App() {
  return (
      <Timeline vertical>
        <Timeline.Item start="Step 1" icon={<CheckCircleIcon />} end="Complete" endBox color="success" />
        <Timeline.Item start="Step 2" loading end="Processing..." endBox />
        <Timeline.Item start="Step 3" icon={<ClockIcon />} end="Pending" endBox />
      </Timeline>
    )
}

export default App

Reverse Order

Reverse the order of timeline items.

First Event
1st
1st
2nd
Second Event
Third Event
3rd
3rd

import { Timeline, Button } from 'asterui'
import { CheckCircleIcon } from '@aster-ui/icons/solid'
import { useState } from 'react'

function App() {
  const [reversed, setReversed] = useState(false);
  
  return (
      <div className="space-y-4">
        <Button size="sm" onClick={() => setReversed(!reversed)}>
          {reversed ? 'Normal Order' : 'Reverse Order'}
        </Button>
        <Timeline vertical reverse={reversed}>
          <Timeline.Item start="1st" icon={<CheckCircleIcon />} end="First Event" endBox />
          <Timeline.Item start="2nd" icon={<CheckCircleIcon />} end="Second Event" endBox />
          <Timeline.Item start="3rd" icon={<CheckCircleIcon />} end="Third Event" endBox />
        </Timeline>
      </div>
    )
}

export default App

Declarative API

Use the items prop for data-driven timelines.

Company Founded
2020
2020
2021
Series A Funding
Global Expansion
2022
2022
2023
IPO

import { Timeline } from 'asterui'
import { CheckCircleIcon } from '@aster-ui/icons/solid'

function App() {
  const items = [
    { key: '1', start: '2020', end: 'Company Founded', endBox: true, icon: <CheckCircleIcon />, color: 'primary' },
    { key: '2', start: '2021', end: 'Series A Funding', endBox: true, icon: <CheckCircleIcon />, color: 'success' },
    { key: '3', start: '2022', end: 'Global Expansion', endBox: true, icon: <CheckCircleIcon />, color: 'info' },
    { key: '4', start: '2023', end: 'IPO', endBox: true, icon: <CheckCircleIcon />, color: 'warning' },
  ];
  
  return (
      <Timeline vertical items={items} />
    )
}

export default App

API

`Timeline`

Property	Description	Type	Default
`children`	Timeline items (compound pattern)	`React.ReactNode`	`-`
`items`	Timeline items (declarative API)	`TimelineItemConfig[]`	`-`
`vertical`	Vertical layout orientation	`boolean`	`false`
`horizontal`	Horizontal layout (default)	`boolean`	`false`
`compact`	All items on one side	`boolean`	`false`
`snapIcon`	Snap icon to start instead of center	`boolean`	`false`
`mode`	Item distribution layout	`'start' \| 'alternate' \| 'end'`	`'alternate'`
`reverse`	Reverse item order	`boolean`	`false`
`pending`	Show pending/loading indicator at end	`React.ReactNode`	`-`
`pendingIcon`	Custom icon for pending item	`React.ReactNode`	`-`
`data-testid`	Test ID for the component	`string`	`'timeline'`
`aria-label`	Accessible label for the timeline	`string`	`-`
`className`	Additional CSS classes	`string`	`-`

`Timeline.Item`

Property	Description	Type	Default
`start`	Content at start position (left/top)	`React.ReactNode`	`-`
`end`	Content at end position (right/bottom)	`React.ReactNode`	`-`
`icon`	Central icon or marker	`React.ReactNode`	`-`
`startBox`	Wrap start content in timeline-box	`boolean`	`false`
`endBox`	Wrap end content in timeline-box	`boolean`	`false`
`color`	Color of the timeline dot/connector	`'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'error' \| 'neutral'`	`-`
`loading`	Show loading spinner instead of icon	`boolean`	`false`
`data-testid`	Test ID for this item	`string`	`-`
`className`	Additional CSS classes	`string`	`-`

`TimelineItemConfig`

Property	Description	Type	Default
`key`	Unique key for the item	`React.Key`	`-`
`start`	Content at start position	`React.ReactNode`	`-`
`end`	Content at end position	`React.ReactNode`	`-`
`icon`	Central icon or marker	`React.ReactNode`	`-`
`startBox`	Wrap start content in timeline-box	`boolean`	`false`
`endBox`	Wrap end content in timeline-box	`boolean`	`false`
`color`	Color of the timeline dot/connector	`TimelineColor`	`-`
`loading`	Show loading spinner	`boolean`	`false`
`className`	Additional CSS classes	`string`	`-`

Accessibility

Uses semantic list structure (role="list") for screen readers
Timeline items are announced in order
Supports aria-label for describing the timeline purpose
Connectors are decorative and hidden from assistive technology
Loading states include visual spinner indicators