Timeline

Events in order, vertical or horizontal, with indicators, dates and a completed state.

New

Completed
Mar 12
Project created
Repository initialised from the starter template.
Mar 14
First deploy
Preview environment went live on the staging domain.
Mar 20
Design review
Tokens and spacing approved by the design team.
Mar 28
Public launch
Production release scheduled after QA sign-off.

1'use client';
2
3import { Timeline } from '@/components/ui/timeline';
4
5const EVENTS = [
6  {
7    step: 1,
8    date: 'Mar 12',
9    title: 'Project created',
10    body: 'Repository initialised from the starter template.',
11  },
12  {
13    step: 2,
14    date: 'Mar 14',
15    title: 'First deploy',
16    body: 'Preview environment went live on the staging domain.',
17  },
18  {
19    step: 3,
20    date: 'Mar 20',
21    title: 'Design review',
22    body: 'Tokens and spacing approved by the design team.',
23  },
24  {
25    step: 4,
26    date: 'Mar 28',
27    title: 'Public launch',
28    body: 'Production release scheduled after QA sign-off.',
29  },
30];
31
32export function Default() {
33  return (
34    <Timeline value={2} className="max-w-md">
35      {EVENTS.map((event) => (
36        <Timeline.Item key={event.step} step={event.step}>
37          <Timeline.Header>
38            <Timeline.Date>{event.date}</Timeline.Date>
39            <Timeline.Title>{event.title}</Timeline.Title>
40          </Timeline.Header>
41          <Timeline.Indicator />
42          <Timeline.Separator />
43          <Timeline.Content>{event.body}</Timeline.Content>
44        </Timeline.Item>
45      ))}
46    </Timeline>
47  );
48}

Installation

Copy and paste the following code into your project.

1'use client';
2
3import { cva, type VariantProps } from 'class-variance-authority';
4import * as React from 'react';
5import { cn } from '../lib/cn';
6
7type TimelineOrientation = 'vertical' | 'horizontal';
8
9interface TimelineLabels {
10  completed: string;
11  list: string;
12}
13
14const DEFAULT_LABELS: TimelineLabels = {
15  completed: 'Completed',
16  list: 'Timeline',
17};
18
19interface TimelineContextValue {
20  orientation: TimelineOrientation;
21  value: number;
22  completedLabel: string;
23}
24
25interface TimelineItemContextValue {
26  step: number;
27  completed: boolean;
28  active: boolean;
29}
30
31const TimelineContext = React.createContext<TimelineContextValue | null>(null);
32const TimelineItemContext = React.createContext<TimelineItemContextValue | null>(null);
33
34function useTimelineContext(): TimelineContextValue {
35  const context = React.use(TimelineContext);
36  if (!context) throw new Error('Timeline components must be used within Timeline');
37  return context;
38}
39
40function useTimelineItemContext(): TimelineItemContextValue {
41  const context = React.use(TimelineItemContext);
42  if (!context) throw new Error('Timeline item parts must be used within Timeline.Item');
43  return context;
44}
45
46const timelineVariants = cva('group/timeline m-0 flex list-none p-0', {
47  variants: {
48    orientation: {
49      vertical: 'flex-col',
50      horizontal:
51        'w-full flex-row overflow-x-auto rounded-sm ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
52    },
53    alternate: {
54      true: '',
55      false: '',
56    },
57  },
58  compoundVariants: [
59    {
60      orientation: 'vertical',
61      alternate: true,
62      className: [
63        'sm:[&>[data-slot=timeline-item]]:w-[calc(50%+0.5rem)]',
64        'sm:[&>[data-slot=timeline-item]:nth-child(odd)]:self-end',
65        'sm:[&>[data-slot=timeline-item]:nth-child(even)]:items-end',
66        'sm:[&>[data-slot=timeline-item]:nth-child(even)]:self-start',
67        'sm:[&>[data-slot=timeline-item]:nth-child(even)]:pe-8',
68        'sm:[&>[data-slot=timeline-item]:nth-child(even)]:ps-0',
69        'sm:[&>[data-slot=timeline-item]:nth-child(even)]:text-end',
70        'sm:[&>[data-slot=timeline-item]:nth-child(even)_[data-slot=timeline-indicator]]:right-2',
71        'sm:[&>[data-slot=timeline-item]:nth-child(even)_[data-slot=timeline-indicator]]:left-auto',
72        'sm:[&>[data-slot=timeline-item]:nth-child(even)_[data-slot=timeline-indicator]]:translate-x-1/2',
73        'sm:[&>[data-slot=timeline-item]:nth-child(even)_[data-slot=timeline-separator]]:right-2',
74        'sm:[&>[data-slot=timeline-item]:nth-child(even)_[data-slot=timeline-separator]]:left-auto',
75        'sm:[&>[data-slot=timeline-item]:nth-child(even)_[data-slot=timeline-separator]]:translate-x-1/2',
76      ].join(' '),
77    },
78  ],
79  defaultVariants: {
80    orientation: 'vertical',
81    alternate: false,
82  },
83});
84
85interface TimelineProps
86  extends
87    Omit<React.HTMLAttributes<HTMLOListElement>, 'defaultValue'>,
88    VariantProps<typeof timelineVariants> {
89  value?: number;
90  labels?: Partial<TimelineLabels>;
91}
92
93interface TimelineItemProps extends React.HTMLAttributes<HTMLLIElement> {
94  step: number;
95}
96
97type TimelineHeaderProps = React.HTMLAttributes<HTMLDivElement>;
98type TimelineDateProps = React.TimeHTMLAttributes<HTMLTimeElement>;
99
100interface TimelineTitleProps extends React.HTMLAttributes<HTMLHeadingElement> {
101  as?: 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
102}
103
104type TimelineIndicatorProps = React.HTMLAttributes<HTMLDivElement>;
105type TimelineSeparatorProps = React.HTMLAttributes<HTMLDivElement>;
106type TimelineContentProps = React.HTMLAttributes<HTMLDivElement>;
107
108const TimelineRoot = ({
109  className,
110  orientation = 'vertical',
111  alternate = false,
112  value = 1,
113  labels: labelOverrides,
114  ref,
115  ...props
116}: TimelineProps & { ref?: React.Ref<HTMLOListElement> }) => {
117  const resolvedOrientation: TimelineOrientation = orientation ?? 'vertical';
118  const labels = { ...DEFAULT_LABELS, ...labelOverrides };
119  const completedLabel = labels.completed;
120  const context = React.useMemo(
121    () => ({ orientation: resolvedOrientation, value, completedLabel }),
122    [resolvedOrientation, value, completedLabel],
123  );
124  const scrollProps =
125    resolvedOrientation === 'horizontal' ? { tabIndex: 0, 'aria-label': labels.list } : undefined;
126
127  return (
128    <TimelineContext value={context}>
129      <ol
130        ref={ref}
131        data-slot="timeline"
132        data-orientation={resolvedOrientation}
133        {...scrollProps}
134        className={cn(timelineVariants({ orientation: resolvedOrientation, alternate }), className)}
135        {...props}
136      />
137    </TimelineContext>
138  );
139};
140
141TimelineRoot.displayName = 'Timeline';
142
143const TimelineItem = ({
144  className,
145  step,
146  children,
147  ref,
148  ...props
149}: TimelineItemProps & { ref?: React.Ref<HTMLLIElement> }) => {
150  const { orientation, value, completedLabel } = useTimelineContext();
151  const completed = step <= value;
152  const active = step === value;
153  const context = React.useMemo(() => ({ step, completed, active }), [step, completed, active]);
154
155  return (
156    <TimelineItemContext value={context}>
157      <li
158        ref={ref}
159        data-slot="timeline-item"
160        data-orientation={orientation}
161        data-completed={completed ? '' : undefined}
162        data-active={active ? '' : undefined}
163        aria-current={active ? 'step' : undefined}
164        className={cn(
165          'group/item relative flex flex-1 flex-col gap-0.5',
166          orientation === 'vertical' ? 'ps-8 pb-8 last:pb-0' : 'min-w-32 pe-8 pt-8 last:pe-0',
167          className,
168        )}
169        {...props}
170      >
171        {completed && !active && completedLabel ? (
172          <span className="sr-only">{completedLabel}</span>
173        ) : null}
174        {children}
175      </li>
176    </TimelineItemContext>
177  );
178};
179
180TimelineItem.displayName = 'TimelineItem';
181
182const TimelineHeader = ({
183  className,
184  ref,
185  ...props
186}: TimelineHeaderProps & { ref?: React.Ref<HTMLDivElement> }) => {
187  return (
188    <div
189      ref={ref}
190      data-slot="timeline-header"
191      className={cn('flex flex-col gap-0.5', className)}
192      {...props}
193    />
194  );
195};
196
197TimelineHeader.displayName = 'TimelineHeader';
198
199const TimelineDate = ({
200  className,
201  ref,
202  ...props
203}: TimelineDateProps & { ref?: React.Ref<HTMLTimeElement> }) => {
204  return (
205    <time
206      ref={ref}
207      data-slot="timeline-date"
208      className={cn('text-muted-foreground block text-xs', className)}
209      {...props}
210    />
211  );
212};
213
214TimelineDate.displayName = 'TimelineDate';
215
216const TimelineTitle = ({
217  className,
218  as: Component = 'h3',
219  ref,
220  ...props
221}: TimelineTitleProps & { ref?: React.Ref<HTMLHeadingElement> }) => {
222  return (
223    <Component
224      ref={ref}
225      data-slot="timeline-title"
226      className={cn('text-foreground text-sm font-medium', className)}
227      {...props}
228    />
229  );
230};
231
232TimelineTitle.displayName = 'TimelineTitle';
233
234const TimelineIndicator = ({
235  className,
236  ref,
237  ...props
238}: TimelineIndicatorProps & { ref?: React.Ref<HTMLDivElement> }) => {
239  const { orientation } = useTimelineContext();
240  useTimelineItemContext();
241
242  return (
243    <div
244      ref={ref}
245      aria-hidden="true"
246      data-slot="timeline-indicator"
247      className={cn(
248        'border-border bg-background absolute z-10 flex size-4 -translate-x-1/2 -translate-y-1/2 items-center justify-center rounded-full border-2 [&_svg]:size-3',
249        'group-data-[completed]/item:border-primary group-data-[completed]/item:bg-primary group-data-[completed]/item:text-primary-foreground',
250        orientation === 'vertical' ? 'top-2.5 left-2' : 'top-2 left-2',
251        className,
252      )}
253      {...props}
254    />
255  );
256};
257
258TimelineIndicator.displayName = 'TimelineIndicator';
259
260const TimelineSeparator = ({
261  className,
262  ref,
263  ...props
264}: TimelineSeparatorProps & { ref?: React.Ref<HTMLDivElement> }) => {
265  const { orientation } = useTimelineContext();
266  useTimelineItemContext();
267
268  return (
269    <div
270      ref={ref}
271      aria-hidden="true"
272      data-slot="timeline-separator"
273      className={cn(
274        'bg-border absolute group-last/item:hidden',
275        'group-data-[completed]/item:bg-primary',
276        orientation === 'vertical'
277          ? 'top-2.5 -bottom-2.5 left-2 w-px -translate-x-1/2'
278          : 'top-2 -right-2 left-2 h-px -translate-y-1/2',
279        className,
280      )}
281      {...props}
282    />
283  );
284};
285
286TimelineSeparator.displayName = 'TimelineSeparator';
287
288const TimelineContent = ({
289  className,
290  ref,
291  ...props
292}: TimelineContentProps & { ref?: React.Ref<HTMLDivElement> }) => {
293  return (
294    <div
295      ref={ref}
296      data-slot="timeline-content"
297      className={cn('text-muted-foreground text-sm', className)}
298      {...props}
299    />
300  );
301};
302
303TimelineContent.displayName = 'TimelineContent';
304
305const Timeline = Object.assign(TimelineRoot, {
306  Item: TimelineItem,
307  Header: TimelineHeader,
308  Date: TimelineDate,
309  Title: TimelineTitle,
310  Indicator: TimelineIndicator,
311  Separator: TimelineSeparator,
312  Content: TimelineContent,
313});
314
315export { Timeline, timelineVariants, useTimelineItemContext };
316export type {
317  TimelineContentProps,
318  TimelineDateProps,
319  TimelineHeaderProps,
320  TimelineIndicatorProps,
321  TimelineItemProps,
322  TimelineLabels,
323  TimelineOrientation,
324  TimelineProps,
325  TimelineSeparatorProps,
326  TimelineTitleProps,
327};

Update the import paths to match your project structure.

Anatomy

1import { Timeline } from '@/components/ui/timeline';

1<Timeline value={2}>
2  <Timeline.Item step={1}>
3    <Timeline.Header>
4      <Timeline.Date>Mar 12</Timeline.Date>
5      <Timeline.Title>Project created</Timeline.Title>
6    </Timeline.Header>
7    <Timeline.Indicator />
8    <Timeline.Separator />
9    <Timeline.Content>Repository initialised from the starter template.</Timeline.Content>
10  </Timeline.Item>
11</Timeline>

Every item declares its step. Items whose step is at or below the timeline value are completed: their indicator fills with the primary color and the separator leading out of them follows. The item at value also gets data-active, so you can style the current step on its own. The root renders an ordered list and each item a list item.

Composition

Use the following composition to build a Timeline:

Timeline
└── Timeline.Item
    ├── Timeline.Header
    │   ├── Timeline.Date
    │   └── Timeline.Title
    ├── Timeline.Indicator
    ├── Timeline.Separator
    └── Timeline.Content

Variants

Horizontal

orientation="horizontal" lays the steps out left to right with the line above the content. Items share the width evenly.

Completed
Mon
Ordered
Completed
Tue
Packed
Wed
Shipped
Fri
Delivered

1'use client';
2
3import { Timeline } from '@/components/ui/timeline';
4
5const STAGES = [
6  { step: 1, date: 'Mon', title: 'Ordered' },
7  { step: 2, date: 'Tue', title: 'Packed' },
8  { step: 3, date: 'Wed', title: 'Shipped' },
9  { step: 4, date: 'Fri', title: 'Delivered' },
10];
11
12export function Horizontal() {
13  return (
14    <Timeline orientation="horizontal" value={3} className="w-full max-w-lg">
15      {STAGES.map((stage) => (
16        <Timeline.Item key={stage.step} step={stage.step}>
17          <Timeline.Header>
18            <Timeline.Date>{stage.date}</Timeline.Date>
19            <Timeline.Title>{stage.title}</Timeline.Title>
20          </Timeline.Header>
21          <Timeline.Indicator />
22          <Timeline.Separator />
23        </Timeline.Item>
24      ))}
25    </Timeline>
26  );
27}

Icons

Pass an icon as the indicator's children and size it with className. Add padding to the item so the content clears the larger marker.

Completed
Commit pushed
feat(ui): add a side-aware caret to the tooltip
Completed
Checks passed
Lint, type-check and 312 tests in 48s.
Merged into main
Squashed by lucia after one approval.
Deployed
Waiting for the production rollout window.

1'use client';
2
3import { Timeline } from '@/components/ui/timeline';
4import { CheckIcon } from '@/components/ui/check';
5import { GitCommitIcon } from '@/components/ui/git-commit';
6import { GitMergeIcon } from '@/components/ui/git-merge';
7import { RocketIcon } from '@/components/ui/rocket';
8
9const STEPS = [
10  {
11    step: 1,
12    icon: GitCommitIcon,
13    title: 'Commit pushed',
14    body: 'feat(ui): add a side-aware caret to the tooltip',
15  },
16  {
17    step: 2,
18    icon: CheckIcon,
19    title: 'Checks passed',
20    body: 'Lint, type-check and 312 tests in 48s.',
21  },
22  {
23    step: 3,
24    icon: GitMergeIcon,
25    title: 'Merged into main',
26    body: 'Squashed by lucia after one approval.',
27  },
28  {
29    step: 4,
30    icon: RocketIcon,
31    title: 'Deployed',
32    body: 'Waiting for the production rollout window.',
33  },
34];
35
36export function Icons() {
37  return (
38    <Timeline value={3} className="max-w-md">
39      {STEPS.map((item) => (
40        <Timeline.Item key={item.step} step={item.step} className="ps-10">
41          <Timeline.Header>
42            <Timeline.Title>{item.title}</Timeline.Title>
43          </Timeline.Header>
44          <Timeline.Indicator className="bg-muted text-muted-foreground size-7 border-0 [&_svg]:size-4">
45            <item.icon />
46          </Timeline.Indicator>
47          <Timeline.Separator />
48          <Timeline.Content>{item.body}</Timeline.Content>
49        </Timeline.Item>
50      ))}
51    </Timeline>
52  );
53}

Alternate

alternate mirrors every other item across the line, for roadmaps and history pages.

Completed
Q1
Discovery
Interviews with twelve teams and a first prototype.
Q2
Private beta
Fifty workspaces onboarded behind a feature flag.
Q3
General availability
Self-serve signup, billing and the public docs.
Q4
Integrations
Slack, Linear and GitHub apps in the marketplace.

1'use client';
2
3import { Timeline } from '@/components/ui/timeline';
4
5const MILESTONES = [
6  {
7    step: 1,
8    date: 'Q1',
9    title: 'Discovery',
10    body: 'Interviews with twelve teams and a first prototype.',
11  },
12  {
13    step: 2,
14    date: 'Q2',
15    title: 'Private beta',
16    body: 'Fifty workspaces onboarded behind a feature flag.',
17  },
18  {
19    step: 3,
20    date: 'Q3',
21    title: 'General availability',
22    body: 'Self-serve signup, billing and the public docs.',
23  },
24  {
25    step: 4,
26    date: 'Q4',
27    title: 'Integrations',
28    body: 'Slack, Linear and GitHub apps in the marketplace.',
29  },
30];
31
32export function Alternate() {
33  return (
34    <Timeline alternate value={2} className="w-full max-w-xl">
35      {MILESTONES.map((milestone) => (
36        <Timeline.Item key={milestone.step} step={milestone.step}>
37          <Timeline.Header>
38            <Timeline.Date>{milestone.date}</Timeline.Date>
39            <Timeline.Title>{milestone.title}</Timeline.Title>
40          </Timeline.Header>
41          <Timeline.Indicator />
42          <Timeline.Separator />
43          <Timeline.Content>{milestone.body}</Timeline.Content>
44        </Timeline.Item>
45      ))}
46    </Timeline>
47  );
48}

Left-aligned dates

Push the item in with a margin and position the date in the gutter. The pieces are plain elements, so a couple of classes are enough.

Completed
09:12
Ticket opened
Customer reported a broken checkout on Safari.
Completed
09:40
Assigned to Nico
Escalated to the payments squad.
Completed
11:05
Fix deployed
Patched the Apple Pay session handshake.
11:30
Resolved
Customer confirmed the order went through.

1'use client';
2
3import { Timeline } from '@/components/ui/timeline';
4
5const ACTIVITY = [
6  {
7    step: 1,
8    date: '09:12',
9    title: 'Ticket opened',
10    body: 'Customer reported a broken checkout on Safari.',
11  },
12  { step: 2, date: '09:40', title: 'Assigned to Nico', body: 'Escalated to the payments squad.' },
13  {
14    step: 3,
15    date: '11:05',
16    title: 'Fix deployed',
17    body: 'Patched the Apple Pay session handshake.',
18  },
19  { step: 4, date: '11:30', title: 'Resolved', body: 'Customer confirmed the order went through.' },
20];
21
22export function LeftDates() {
23  return (
24    <Timeline value={4} className="max-w-lg">
25      {ACTIVITY.map((entry) => (
26        <Timeline.Item key={entry.step} step={entry.step} className="ms-16">
27          <Timeline.Header>
28            <Timeline.Date className="absolute -start-16 top-0.5 w-14 text-end font-mono">
29              {entry.date}
30            </Timeline.Date>
31            <Timeline.Title>{entry.title}</Timeline.Title>
32          </Timeline.Header>
33          <Timeline.Indicator />
34          <Timeline.Separator />
35          <Timeline.Content>{entry.body}</Timeline.Content>
36        </Timeline.Item>
37      ))}
38    </Timeline>
39  );
40}

API Reference

Timeline

Prop	Type	Default	Description
`value`	`number`	`1`	Steps at or below this value are completed
`orientation`	`'vertical' \| 'horizontal'`	`'vertical'`	Layout direction
`alternate`	`boolean`	`false`	Mirror every other item across the line (vertical, from the `sm` breakpoint up)
`labels`	`Partial<TimelineLabels>`	-	Screen reader text: `completed` (`"Completed"`) is read on finished steps and `list` (`"Timeline"`) names the horizontal scroller.
`className`	`string`	-	Additional CSS classes

Timeline.Item

Prop	Type	Default	Description
`step`	`number`	-	Position of the item, compared against `value`
`className`	`string`	-	Additional CSS classes

Exposes data-completed and data-active for styling. The active item also gets aria-current="step", and finished items carry the completed label as visually hidden text.

Timeline.Title

Prop	Type	Default	Description
`as`	`'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'`	`'h3'`	Heading level
`className`	`string`	-	Additional CSS classes

Timeline.Date

Renders a time element and accepts dateTime plus className.

Timeline.Header, Timeline.Indicator, Timeline.Separator, Timeline.Content

Layout parts of an item. Each accepts className and standard div props. The indicator takes children for a custom marker.

Found something to improve?

Notice a bug, typo, or missing detail on this page? Help us make the documentation better by opening a GitHub issue.

Create an Issue

PreviousTextarea

NextToast

Timeline

Events in order, vertical or horizontal, with indicators, dates and a completed state.

New

Completed
Mar 12
Project created
Repository initialised from the starter template.
Mar 14
First deploy
Preview environment went live on the staging domain.
Mar 20
Design review
Tokens and spacing approved by the design team.
Mar 28
Public launch
Production release scheduled after QA sign-off.

1'use client';
2
3import { Timeline } from '@/components/ui/timeline';
4
5const EVENTS = [
6  {
7    step: 1,
8    date: 'Mar 12',
9    title: 'Project created',
10    body: 'Repository initialised from the starter template.',
11  },
12  {
13    step: 2,
14    date: 'Mar 14',
15    title: 'First deploy',
16    body: 'Preview environment went live on the staging domain.',
17  },
18  {
19    step: 3,
20    date: 'Mar 20',
21    title: 'Design review',
22    body: 'Tokens and spacing approved by the design team.',
23  },
24  {
25    step: 4,
26    date: 'Mar 28',
27    title: 'Public launch',
28    body: 'Production release scheduled after QA sign-off.',
29  },
30];
31
32export function Default() {
33  return (
34    <Timeline value={2} className="max-w-md">
35      {EVENTS.map((event) => (
36        <Timeline.Item key={event.step} step={event.step}>
37          <Timeline.Header>
38            <Timeline.Date>{event.date}</Timeline.Date>
39            <Timeline.Title>{event.title}</Timeline.Title>
40          </Timeline.Header>
41          <Timeline.Indicator />
42          <Timeline.Separator />
43          <Timeline.Content>{event.body}</Timeline.Content>
44        </Timeline.Item>
45      ))}
46    </Timeline>
47  );
48}

Installation

Copy and paste the following code into your project.

1'use client';
2
3import { cva, type VariantProps } from 'class-variance-authority';
4import * as React from 'react';
5import { cn } from '../lib/cn';
6
7type TimelineOrientation = 'vertical' | 'horizontal';
8
9interface TimelineLabels {
10  completed: string;
11  list: string;
12}
13
14const DEFAULT_LABELS: TimelineLabels = {
15  completed: 'Completed',
16  list: 'Timeline',
17};
18
19interface TimelineContextValue {
20  orientation: TimelineOrientation;
21  value: number;
22  completedLabel: string;
23}
24
25interface TimelineItemContextValue {
26  step: number;
27  completed: boolean;
28  active: boolean;
29}
30
31const TimelineContext = React.createContext<TimelineContextValue | null>(null);
32const TimelineItemContext = React.createContext<TimelineItemContextValue | null>(null);
33
34function useTimelineContext(): TimelineContextValue {
35  const context = React.use(TimelineContext);
36  if (!context) throw new Error('Timeline components must be used within Timeline');
37  return context;
38}
39
40function useTimelineItemContext(): TimelineItemContextValue {
41  const context = React.use(TimelineItemContext);
42  if (!context) throw new Error('Timeline item parts must be used within Timeline.Item');
43  return context;
44}
45
46const timelineVariants = cva('group/timeline m-0 flex list-none p-0', {
47  variants: {
48    orientation: {
49      vertical: 'flex-col',
50      horizontal:
51        'w-full flex-row overflow-x-auto rounded-sm ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
52    },
53    alternate: {
54      true: '',
55      false: '',
56    },
57  },
58  compoundVariants: [
59    {
60      orientation: 'vertical',
61      alternate: true,
62      className: [
63        'sm:[&>[data-slot=timeline-item]]:w-[calc(50%+0.5rem)]',
64        'sm:[&>[data-slot=timeline-item]:nth-child(odd)]:self-end',
65        'sm:[&>[data-slot=timeline-item]:nth-child(even)]:items-end',
66        'sm:[&>[data-slot=timeline-item]:nth-child(even)]:self-start',
67        'sm:[&>[data-slot=timeline-item]:nth-child(even)]:pe-8',
68        'sm:[&>[data-slot=timeline-item]:nth-child(even)]:ps-0',
69        'sm:[&>[data-slot=timeline-item]:nth-child(even)]:text-end',
70        'sm:[&>[data-slot=timeline-item]:nth-child(even)_[data-slot=timeline-indicator]]:right-2',
71        'sm:[&>[data-slot=timeline-item]:nth-child(even)_[data-slot=timeline-indicator]]:left-auto',
72        'sm:[&>[data-slot=timeline-item]:nth-child(even)_[data-slot=timeline-indicator]]:translate-x-1/2',
73        'sm:[&>[data-slot=timeline-item]:nth-child(even)_[data-slot=timeline-separator]]:right-2',
74        'sm:[&>[data-slot=timeline-item]:nth-child(even)_[data-slot=timeline-separator]]:left-auto',
75        'sm:[&>[data-slot=timeline-item]:nth-child(even)_[data-slot=timeline-separator]]:translate-x-1/2',
76      ].join(' '),
77    },
78  ],
79  defaultVariants: {
80    orientation: 'vertical',
81    alternate: false,
82  },
83});
84
85interface TimelineProps
86  extends
87    Omit<React.HTMLAttributes<HTMLOListElement>, 'defaultValue'>,
88    VariantProps<typeof timelineVariants> {
89  value?: number;
90  labels?: Partial<TimelineLabels>;
91}
92
93interface TimelineItemProps extends React.HTMLAttributes<HTMLLIElement> {
94  step: number;
95}
96
97type TimelineHeaderProps = React.HTMLAttributes<HTMLDivElement>;
98type TimelineDateProps = React.TimeHTMLAttributes<HTMLTimeElement>;
99
100interface TimelineTitleProps extends React.HTMLAttributes<HTMLHeadingElement> {
101  as?: 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
102}
103
104type TimelineIndicatorProps = React.HTMLAttributes<HTMLDivElement>;
105type TimelineSeparatorProps = React.HTMLAttributes<HTMLDivElement>;
106type TimelineContentProps = React.HTMLAttributes<HTMLDivElement>;
107
108const TimelineRoot = ({
109  className,
110  orientation = 'vertical',
111  alternate = false,
112  value = 1,
113  labels: labelOverrides,
114  ref,
115  ...props
116}: TimelineProps & { ref?: React.Ref<HTMLOListElement> }) => {
117  const resolvedOrientation: TimelineOrientation = orientation ?? 'vertical';
118  const labels = { ...DEFAULT_LABELS, ...labelOverrides };
119  const completedLabel = labels.completed;
120  const context = React.useMemo(
121    () => ({ orientation: resolvedOrientation, value, completedLabel }),
122    [resolvedOrientation, value, completedLabel],
123  );
124  const scrollProps =
125    resolvedOrientation === 'horizontal' ? { tabIndex: 0, 'aria-label': labels.list } : undefined;
126
127  return (
128    <TimelineContext value={context}>
129      <ol
130        ref={ref}
131        data-slot="timeline"
132        data-orientation={resolvedOrientation}
133        {...scrollProps}
134        className={cn(timelineVariants({ orientation: resolvedOrientation, alternate }), className)}
135        {...props}
136      />
137    </TimelineContext>
138  );
139};
140
141TimelineRoot.displayName = 'Timeline';
142
143const TimelineItem = ({
144  className,
145  step,
146  children,
147  ref,
148  ...props
149}: TimelineItemProps & { ref?: React.Ref<HTMLLIElement> }) => {
150  const { orientation, value, completedLabel } = useTimelineContext();
151  const completed = step <= value;
152  const active = step === value;
153  const context = React.useMemo(() => ({ step, completed, active }), [step, completed, active]);
154
155  return (
156    <TimelineItemContext value={context}>
157      <li
158        ref={ref}
159        data-slot="timeline-item"
160        data-orientation={orientation}
161        data-completed={completed ? '' : undefined}
162        data-active={active ? '' : undefined}
163        aria-current={active ? 'step' : undefined}
164        className={cn(
165          'group/item relative flex flex-1 flex-col gap-0.5',
166          orientation === 'vertical' ? 'ps-8 pb-8 last:pb-0' : 'min-w-32 pe-8 pt-8 last:pe-0',
167          className,
168        )}
169        {...props}
170      >
171        {completed && !active && completedLabel ? (
172          <span className="sr-only">{completedLabel}</span>
173        ) : null}
174        {children}
175      </li>
176    </TimelineItemContext>
177  );
178};
179
180TimelineItem.displayName = 'TimelineItem';
181
182const TimelineHeader = ({
183  className,
184  ref,
185  ...props
186}: TimelineHeaderProps & { ref?: React.Ref<HTMLDivElement> }) => {
187  return (
188    <div
189      ref={ref}
190      data-slot="timeline-header"
191      className={cn('flex flex-col gap-0.5', className)}
192      {...props}
193    />
194  );
195};
196
197TimelineHeader.displayName = 'TimelineHeader';
198
199const TimelineDate = ({
200  className,
201  ref,
202  ...props
203}: TimelineDateProps & { ref?: React.Ref<HTMLTimeElement> }) => {
204  return (
205    <time
206      ref={ref}
207      data-slot="timeline-date"
208      className={cn('text-muted-foreground block text-xs', className)}
209      {...props}
210    />
211  );
212};
213
214TimelineDate.displayName = 'TimelineDate';
215
216const TimelineTitle = ({
217  className,
218  as: Component = 'h3',
219  ref,
220  ...props
221}: TimelineTitleProps & { ref?: React.Ref<HTMLHeadingElement> }) => {
222  return (
223    <Component
224      ref={ref}
225      data-slot="timeline-title"
226      className={cn('text-foreground text-sm font-medium', className)}
227      {...props}
228    />
229  );
230};
231
232TimelineTitle.displayName = 'TimelineTitle';
233
234const TimelineIndicator = ({
235  className,
236  ref,
237  ...props
238}: TimelineIndicatorProps & { ref?: React.Ref<HTMLDivElement> }) => {
239  const { orientation } = useTimelineContext();
240  useTimelineItemContext();
241
242  return (
243    <div
244      ref={ref}
245      aria-hidden="true"
246      data-slot="timeline-indicator"
247      className={cn(
248        'border-border bg-background absolute z-10 flex size-4 -translate-x-1/2 -translate-y-1/2 items-center justify-center rounded-full border-2 [&_svg]:size-3',
249        'group-data-[completed]/item:border-primary group-data-[completed]/item:bg-primary group-data-[completed]/item:text-primary-foreground',
250        orientation === 'vertical' ? 'top-2.5 left-2' : 'top-2 left-2',
251        className,
252      )}
253      {...props}
254    />
255  );
256};
257
258TimelineIndicator.displayName = 'TimelineIndicator';
259
260const TimelineSeparator = ({
261  className,
262  ref,
263  ...props
264}: TimelineSeparatorProps & { ref?: React.Ref<HTMLDivElement> }) => {
265  const { orientation } = useTimelineContext();
266  useTimelineItemContext();
267
268  return (
269    <div
270      ref={ref}
271      aria-hidden="true"
272      data-slot="timeline-separator"
273      className={cn(
274        'bg-border absolute group-last/item:hidden',
275        'group-data-[completed]/item:bg-primary',
276        orientation === 'vertical'
277          ? 'top-2.5 -bottom-2.5 left-2 w-px -translate-x-1/2'
278          : 'top-2 -right-2 left-2 h-px -translate-y-1/2',
279        className,
280      )}
281      {...props}
282    />
283  );
284};
285
286TimelineSeparator.displayName = 'TimelineSeparator';
287
288const TimelineContent = ({
289  className,
290  ref,
291  ...props
292}: TimelineContentProps & { ref?: React.Ref<HTMLDivElement> }) => {
293  return (
294    <div
295      ref={ref}
296      data-slot="timeline-content"
297      className={cn('text-muted-foreground text-sm', className)}
298      {...props}
299    />
300  );
301};
302
303TimelineContent.displayName = 'TimelineContent';
304
305const Timeline = Object.assign(TimelineRoot, {
306  Item: TimelineItem,
307  Header: TimelineHeader,
308  Date: TimelineDate,
309  Title: TimelineTitle,
310  Indicator: TimelineIndicator,
311  Separator: TimelineSeparator,
312  Content: TimelineContent,
313});
314
315export { Timeline, timelineVariants, useTimelineItemContext };
316export type {
317  TimelineContentProps,
318  TimelineDateProps,
319  TimelineHeaderProps,
320  TimelineIndicatorProps,
321  TimelineItemProps,
322  TimelineLabels,
323  TimelineOrientation,
324  TimelineProps,
325  TimelineSeparatorProps,
326  TimelineTitleProps,
327};

Update the import paths to match your project structure.

Anatomy

1import { Timeline } from '@/components/ui/timeline';

1<Timeline value={2}>
2  <Timeline.Item step={1}>
3    <Timeline.Header>
4      <Timeline.Date>Mar 12</Timeline.Date>
5      <Timeline.Title>Project created</Timeline.Title>
6    </Timeline.Header>
7    <Timeline.Indicator />
8    <Timeline.Separator />
9    <Timeline.Content>Repository initialised from the starter template.</Timeline.Content>
10  </Timeline.Item>
11</Timeline>

Composition

Use the following composition to build a Timeline:

Timeline
└── Timeline.Item
    ├── Timeline.Header
    │   ├── Timeline.Date
    │   └── Timeline.Title
    ├── Timeline.Indicator
    ├── Timeline.Separator
    └── Timeline.Content

Variants

Horizontal

orientation="horizontal" lays the steps out left to right with the line above the content. Items share the width evenly.

Completed
Mon
Ordered
Completed
Tue
Packed
Wed
Shipped
Fri
Delivered

1'use client';
2
3import { Timeline } from '@/components/ui/timeline';
4
5const STAGES = [
6  { step: 1, date: 'Mon', title: 'Ordered' },
7  { step: 2, date: 'Tue', title: 'Packed' },
8  { step: 3, date: 'Wed', title: 'Shipped' },
9  { step: 4, date: 'Fri', title: 'Delivered' },
10];
11
12export function Horizontal() {
13  return (
14    <Timeline orientation="horizontal" value={3} className="w-full max-w-lg">
15      {STAGES.map((stage) => (
16        <Timeline.Item key={stage.step} step={stage.step}>
17          <Timeline.Header>
18            <Timeline.Date>{stage.date}</Timeline.Date>
19            <Timeline.Title>{stage.title}</Timeline.Title>
20          </Timeline.Header>
21          <Timeline.Indicator />
22          <Timeline.Separator />
23        </Timeline.Item>
24      ))}
25    </Timeline>
26  );
27}

Icons

Pass an icon as the indicator's children and size it with className. Add padding to the item so the content clears the larger marker.

Completed
Commit pushed
feat(ui): add a side-aware caret to the tooltip
Completed
Checks passed
Lint, type-check and 312 tests in 48s.
Merged into main
Squashed by lucia after one approval.
Deployed
Waiting for the production rollout window.

1'use client';
2
3import { Timeline } from '@/components/ui/timeline';
4import { CheckIcon } from '@/components/ui/check';
5import { GitCommitIcon } from '@/components/ui/git-commit';
6import { GitMergeIcon } from '@/components/ui/git-merge';
7import { RocketIcon } from '@/components/ui/rocket';
8
9const STEPS = [
10  {
11    step: 1,
12    icon: GitCommitIcon,
13    title: 'Commit pushed',
14    body: 'feat(ui): add a side-aware caret to the tooltip',
15  },
16  {
17    step: 2,
18    icon: CheckIcon,
19    title: 'Checks passed',
20    body: 'Lint, type-check and 312 tests in 48s.',
21  },
22  {
23    step: 3,
24    icon: GitMergeIcon,
25    title: 'Merged into main',
26    body: 'Squashed by lucia after one approval.',
27  },
28  {
29    step: 4,
30    icon: RocketIcon,
31    title: 'Deployed',
32    body: 'Waiting for the production rollout window.',
33  },
34];
35
36export function Icons() {
37  return (
38    <Timeline value={3} className="max-w-md">
39      {STEPS.map((item) => (
40        <Timeline.Item key={item.step} step={item.step} className="ps-10">
41          <Timeline.Header>
42            <Timeline.Title>{item.title}</Timeline.Title>
43          </Timeline.Header>
44          <Timeline.Indicator className="bg-muted text-muted-foreground size-7 border-0 [&_svg]:size-4">
45            <item.icon />
46          </Timeline.Indicator>
47          <Timeline.Separator />
48          <Timeline.Content>{item.body}</Timeline.Content>
49        </Timeline.Item>
50      ))}
51    </Timeline>
52  );
53}

Alternate

alternate mirrors every other item across the line, for roadmaps and history pages.

Completed
Q1
Discovery
Interviews with twelve teams and a first prototype.
Q2
Private beta
Fifty workspaces onboarded behind a feature flag.
Q3
General availability
Self-serve signup, billing and the public docs.
Q4
Integrations
Slack, Linear and GitHub apps in the marketplace.

1'use client';
2
3import { Timeline } from '@/components/ui/timeline';
4
5const MILESTONES = [
6  {
7    step: 1,
8    date: 'Q1',
9    title: 'Discovery',
10    body: 'Interviews with twelve teams and a first prototype.',
11  },
12  {
13    step: 2,
14    date: 'Q2',
15    title: 'Private beta',
16    body: 'Fifty workspaces onboarded behind a feature flag.',
17  },
18  {
19    step: 3,
20    date: 'Q3',
21    title: 'General availability',
22    body: 'Self-serve signup, billing and the public docs.',
23  },
24  {
25    step: 4,
26    date: 'Q4',
27    title: 'Integrations',
28    body: 'Slack, Linear and GitHub apps in the marketplace.',
29  },
30];
31
32export function Alternate() {
33  return (
34    <Timeline alternate value={2} className="w-full max-w-xl">
35      {MILESTONES.map((milestone) => (
36        <Timeline.Item key={milestone.step} step={milestone.step}>
37          <Timeline.Header>
38            <Timeline.Date>{milestone.date}</Timeline.Date>
39            <Timeline.Title>{milestone.title}</Timeline.Title>
40          </Timeline.Header>
41          <Timeline.Indicator />
42          <Timeline.Separator />
43          <Timeline.Content>{milestone.body}</Timeline.Content>
44        </Timeline.Item>
45      ))}
46    </Timeline>
47  );
48}

Left-aligned dates

Push the item in with a margin and position the date in the gutter. The pieces are plain elements, so a couple of classes are enough.

Completed
09:12
Ticket opened
Customer reported a broken checkout on Safari.
Completed
09:40
Assigned to Nico
Escalated to the payments squad.
Completed
11:05
Fix deployed
Patched the Apple Pay session handshake.
11:30
Resolved
Customer confirmed the order went through.

1'use client';
2
3import { Timeline } from '@/components/ui/timeline';
4
5const ACTIVITY = [
6  {
7    step: 1,
8    date: '09:12',
9    title: 'Ticket opened',
10    body: 'Customer reported a broken checkout on Safari.',
11  },
12  { step: 2, date: '09:40', title: 'Assigned to Nico', body: 'Escalated to the payments squad.' },
13  {
14    step: 3,
15    date: '11:05',
16    title: 'Fix deployed',
17    body: 'Patched the Apple Pay session handshake.',
18  },
19  { step: 4, date: '11:30', title: 'Resolved', body: 'Customer confirmed the order went through.' },
20];
21
22export function LeftDates() {
23  return (
24    <Timeline value={4} className="max-w-lg">
25      {ACTIVITY.map((entry) => (
26        <Timeline.Item key={entry.step} step={entry.step} className="ms-16">
27          <Timeline.Header>
28            <Timeline.Date className="absolute -start-16 top-0.5 w-14 text-end font-mono">
29              {entry.date}
30            </Timeline.Date>
31            <Timeline.Title>{entry.title}</Timeline.Title>
32          </Timeline.Header>
33          <Timeline.Indicator />
34          <Timeline.Separator />
35          <Timeline.Content>{entry.body}</Timeline.Content>
36        </Timeline.Item>
37      ))}
38    </Timeline>
39  );
40}

API Reference

Timeline

Prop	Type	Default	Description
`value`	`number`	`1`	Steps at or below this value are completed
`orientation`	`'vertical' \| 'horizontal'`	`'vertical'`	Layout direction
`alternate`	`boolean`	`false`	Mirror every other item across the line (vertical, from the `sm` breakpoint up)
`labels`	`Partial<TimelineLabels>`	-	Screen reader text: `completed` (`"Completed"`) is read on finished steps and `list` (`"Timeline"`) names the horizontal scroller.
`className`	`string`	-	Additional CSS classes

Timeline.Item

Prop	Type	Default	Description
`step`	`number`	-	Position of the item, compared against `value`
`className`	`string`	-	Additional CSS classes

Exposes data-completed and data-active for styling. The active item also gets aria-current="step", and finished items carry the completed label as visually hidden text.

Timeline.Title

Prop	Type	Default	Description
`as`	`'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'`	`'h3'`	Heading level
`className`	`string`	-	Additional CSS classes

Timeline.Date

Renders a time element and accepts dateTime plus className.

Timeline.Header, Timeline.Indicator, Timeline.Separator, Timeline.Content

Layout parts of an item. Each accepts className and standard div props. The indicator takes children for a custom marker.

Found something to improve?

Notice a bug, typo, or missing detail on this page? Help us make the documentation better by opening a GitHub issue.

Create an Issue

PreviousTextarea

NextToast