Timeline

import { Canvas, Controls, Meta, Title } from '@storybook/addon-docs/blocks';

import * as TimelineStories from './Timeline.stories';

<Meta of={TimelineStories} name='Usage' />

<Title />

## Purpose

A list of events over time, with an optional rail that joins their icons.

## Usage

Use it for an event log, a deploy history or an agent's run: anything that reads top to bottom in time order.

- Each child becomes a list item. `TimelineItem`s are joined by the rail; a divider, a Chain of Thought or a Thinking State in between breaks it.
- Turn on `hasRail` for a log of events over time, especially with timestamps, where people scan down to find when something happened. Dividers split the log into segments, since they break the rail.
- Leave it off where the list sits under a summary line, as in Chain of Thought, and for a short progress list with no timestamps; the status icons already show the order.
- For rows with large content under them (logs, diagrams, screenshots), start without a rail.
- To show an agent joining a log, put an agentic Labeled Divider before its items and mark them `isAgentic`.

## Timeline or Chain of Thought?

A Timeline is a list of events in time order, always open, with an optional rail and no summary. A Chain of Thought is a collapsible group for an agent's reasoning: a summary line (a Thinking State with a chevron) that opens on demand, with a Timeline's rows underneath and no rail. Use a Timeline where the history is the content (an event log); use a Chain of Thought where the steps support a reply and should stay out of the way. A Chain of Thought can also sit inside a Timeline, as one entry.

## Implementation

See the table below for the available props. Timeline Item has its own page.

<hr />

<Canvas of={TimelineStories.Default} />
<Controls of={TimelineStories.Default} />