Timeline

A timeline component that displays events with customizable orientation, alignment, and spacing. A visual representation of events in chronological order.

March 2024

Project Initialized

Successfully set up the project repository and initial architecture.

April 2024

Beta Release

Launched the beta version for early testers and feedback.

June 2024

Official Launch

The platform is now live for all users worldwide.

1
import {
2
  Timeline,
3
  TimelineContent,
4
  TimelineDate,
5
  TimelineHeader,
6
  TimelineIndicator,
7
  TimelineItem,
8
  TimelineSeparator,
9
  TimelineTitle,
10
} from "@/components/ui/pxl/timeline";
11

12
export default function TimelineDemo() {
13
  return (
14
    <Timeline defaultValue={2} className="w-full max-w-md">
15
      <TimelineItem step={1}>
16
        <TimelineHeader>
17
          <TimelineDate>March 2024</TimelineDate>
18
          <TimelineTitle>Project Initialized</TimelineTitle>
19
        </TimelineHeader>
20
        <TimelineIndicator />
21
        <TimelineSeparator />
22
        <TimelineContent>
23
          Successfully set up the project repository and initial architecture.
24
        </TimelineContent>
25
      </TimelineItem>
26

27
      <TimelineItem step={2}>
28
        <TimelineHeader>
29
          <TimelineDate>April 2024</TimelineDate>
30
          <TimelineTitle>Beta Release</TimelineTitle>
31
        </TimelineHeader>
32
        <TimelineIndicator />
33
        <TimelineSeparator />
34
        <TimelineContent>
35
          Launched the beta version for early testers and feedback.
36
        </TimelineContent>
37
      </TimelineItem>
38

39
      <TimelineItem step={3}>
40
        <TimelineHeader>
41
          <TimelineDate>June 2024</TimelineDate>
42
          <TimelineTitle>Official Launch</TimelineTitle>
43
        </TimelineHeader>
44
        <TimelineIndicator />
45
        <TimelineSeparator />
46
        <TimelineContent>
47
          The platform is now live for all users worldwide.
48
        </TimelineContent>
49
      </TimelineItem>
50
    </Timeline>
51
  );
52
}

pnpm dlx shadcn@latest add pxl-ui/registry/timeline

Copy and paste the following code into your project.

1
import { mergeProps } from "@base-ui/react/merge-props";
2
import { useRender } from "@base-ui/react/use-render";
3
import { createContext, useCallback, useContext, useState } from "react";
4

5
import { cn } from "@/lib/utils";
6

7
const TimelineContext = createContext<
8
  | {
9
      activeStep: number;
10
      setActiveStep: (step: number) => void;
11
    }
12
  | undefined
13
>(undefined);
14

15
const useTimeline = () => {
16
  const context = useContext(TimelineContext);
17
  if (!context) {
18
    throw new Error("useTimeline must be used within a Timeline");
19
  }
20
  return context;
21
};
22

23
function Timeline({
24
  defaultValue = 1,
25
  value,
26
  onValueChange,
27
  orientation = "vertical",
28
  className,
29
  render,
30
  children,
31
  ...props
32
}: useRender.ComponentProps<"div"> & {
33
  defaultValue?: number;
34
  value?: number;
35
  onValueChange?: (value: number) => void;
36
  orientation?: "horizontal" | "vertical";
37
}) {
38
  const [activeStep, setInternalStep] = useState(defaultValue);
39

40
  const setActiveStep = useCallback(
41
    (step: number) => {
42
      if (value === undefined) {
43
        setInternalStep(step);
44
      }
45
      onValueChange?.(step);
46
    },
47
    [value, onValueChange],
48
  );
49

50
  const currentStep = value ?? activeStep;
51

52
  const defaultProps = {
53
    className: cn(
54
      "group/timeline flex data-[orientation=horizontal]:w-full data-[orientation=horizontal]:flex-row data-[orientation=vertical]:flex-col",
55
      className,
56
    ),
57
    "data-orientation": orientation,
58
    "data-slot": "timeline",
59
    children,
60
  };
61

62
  return (
63
    <TimelineContext.Provider
64
      value={{ activeStep: currentStep, setActiveStep }}
65
    >
66
      {useRender({
67
        defaultTagName: "div",
68
        render,
69
        props: mergeProps<"div">(defaultProps, props),
70
      })}
71
    </TimelineContext.Provider>
72
  );
73
}
74

75
function TimelineContent({
76
  className,
77
  render,
78
  children,
79
  ...props
80
}: useRender.ComponentProps<"div">) {
81
  const defaultProps = {
82
    className: cn("text-muted-foreground text-sm", className),
83
    "data-slot": "timeline-content",
84
    children,
85
  };
86

87
  return useRender({
88
    defaultTagName: "div",
89
    render,
90
    props: mergeProps<"div">(defaultProps, props),
91
  });
92
}
93

94
function TimelineDate({
95
  className,
96
  render,
97
  children,
98
  ...props
99
}: useRender.ComponentProps<"time">) {
100
  const defaultProps = {
101
    className: cn(
102
      "mb-1 block font-medium text-muted-foreground text-xs group-data-[orientation=vertical]/timeline:max-sm:h-4",
103
      className,
104
    ),
105
    "data-slot": "timeline-date",
106
    children,
107
  };
108

109
  return useRender({
110
    defaultTagName: "time",
111
    render,
112
    props: mergeProps<"time">(defaultProps, props),
113
  });
114
}
115

116
function TimelineHeader({
117
  className,
118
  render,
119
  children,
120
  ...props
121
}: useRender.ComponentProps<"div">) {
122
  const defaultProps = {
123
    className: cn(className),
124
    "data-slot": "timeline-header",
125
    children,
126
  };
127

128
  return useRender({
129
    defaultTagName: "div",
130
    render,
131
    props: mergeProps<"div">(defaultProps, props),
132
  });
133
}
134

135
function TimelineIndicator({
136
  className,
137
  children,
138
  render,
139
  ...props
140
}: useRender.ComponentProps<"div">) {
141
  const defaultProps = {
142
    "aria-hidden": true,
143
    className: cn(
144
      "group-data-[orientation=horizontal]/timeline:-top-6 group-data-[orientation=horizontal]/timeline:-translate-y-1/2 group-data-[orientation=vertical]/timeline:-left-6 group-data-[orientation=vertical]/timeline:-translate-x-1/2 absolute size-4 pixel-size-lg pixel-border pixel-color-foreground/20 group-data-[orientation=vertical]/timeline:top-0 group-data-[orientation=horizontal]/timeline:left-0 group-data-completed/timeline-item:pixel-color-foreground",
145
      className,
146
    ),
147
    "data-slot": "timeline-indicator",
148
    children,
149
  };
150

151
  return useRender({
152
    defaultTagName: "div",
153
    render,
154
    props: mergeProps<"div">(defaultProps, props),
155
  });
156
}
157

158
function TimelineItem({
159
  step,
160
  className,
161
  render,
162
  children,
163
  ...props
164
}: useRender.ComponentProps<"div"> & {
165
  step: number;
166
}) {
167
  const { activeStep } = useTimeline();
168

169
  const defaultProps = {
170
    className: cn(
171
      "group/timeline-item relative flex flex-1 flex-col gap-0.5 group-data-[orientation=vertical]/timeline:ms-8 group-data-[orientation=horizontal]/timeline:mt-8 group-data-[orientation=horizontal]/timeline:not-last:pe-8 group-data-[orientation=vertical]/timeline:not-last:pb-6 has-[+[data-completed]]:**:data-[slot=timeline-separator]:bg-foreground",
172
      className,
173
    ),
174
    "data-completed": step <= activeStep || undefined,
175
    "data-slot": "timeline-item",
176
    children,
177
  };
178

179
  return useRender({
180
    defaultTagName: "div",
181
    render,
182
    props: mergeProps<"div">(defaultProps, props),
183
  });
184
}
185

186
function TimelineSeparator({
187
  className,
188
  render,
189
  children,
190
  ...props
191
}: useRender.ComponentProps<"div">) {
192
  const defaultProps = {
193
    "aria-hidden": true,
194
    className: cn(
195
      "group-data-[orientation=horizontal]/timeline:-top-6 group-data-[orientation=horizontal]/timeline:-translate-y-1/2 group-data-[orientation=vertical]/timeline:-left-6 group-data-[orientation=vertical]/timeline:-translate-x-1/2 absolute self-start bg-foreground/10 group-last/timeline-item:hidden group-data-[orientation=horizontal]/timeline:h-1 group-data-[orientation=vertical]/timeline:h-[calc(100%-1rem)] group-data-[orientation=horizontal]/timeline:w-[calc(100%-1rem)] group-data-[orientation=vertical]/timeline:w-1 group-data-[orientation=horizontal]/timeline:translate-x-4 group-data-[orientation=vertical]/timeline:translate-y-4",
196
      className,
197
    ),
198
    "data-slot": "timeline-separator",
199
    children,
200
  };
201

202
  return useRender({
203
    defaultTagName: "div",
204
    render,
205
    props: mergeProps<"div">(defaultProps, props),
206
  });
207
}
208

209
function TimelineTitle({
210
  className,
211
  render,
212
  children,
213
  ...props
214
}: useRender.ComponentProps<"h3">) {
215
  const defaultProps = {
216
    className: cn("font-medium text-sm", className),
217
    "data-slot": "timeline-title",
218
    children,
219
  };
220

221
  return useRender({
222
    defaultTagName: "h3",
223
    render,
224
    props: mergeProps<"h3">(defaultProps, props),
225
  });
226
}
227

228
export {
229
  Timeline,
230
  TimelineContent,
231
  TimelineDate,
232
  TimelineHeader,
233
  TimelineIndicator,
234
  TimelineItem,
235
  TimelineSeparator,
236
  TimelineTitle,
237
};

Update the import paths to match your project setup.

Usage

import {
  Timeline,
  TimelineContent,
  TimelineDate,
  TimelineHeader,
  TimelineIndicator,
  TimelineItem,
  TimelineSeparator,
  TimelineTitle,
} from "@/components/reui/timeline"

<Timeline>
  <TimelineItem step={1}>
    <TimelineHeader>
      <TimelineDate>March 2024</TimelineDate>
      <TimelineTitle>Project Initialized</TimelineTitle>
    </TimelineHeader>
    <TimelineIndicator />
    <TimelineSeparator />
    <TimelineContent>
      Successfully set up the project repository and initial architecture.
    </TimelineContent>
  </TimelineItem>
</Timeline>

Horizontal Orientation

Week 1

Planning

Scope definition and resource planning.

Week 2

Design

UI/UX design and prototyping.

Week 4

Development

Core features implementation.

1
import {
2
  Timeline,
3
  TimelineContent,
4
  TimelineDate,
5
  TimelineHeader,
6
  TimelineIndicator,
7
  TimelineItem,
8
  TimelineSeparator,
9
  TimelineTitle,
10
} from "@/components/ui/pxl/timeline";
11

12
const releaseCycle = [
13
  {
14
    id: 1,
15
    date: "Week 1",
16
    title: "Planning",
17
    description: "Scope definition and resource planning.",
18
  },
19
  {
20
    id: 2,
21
    date: "Week 2",
22
    title: "Design",
23
    description: "UI/UX design and prototyping.",
24
  },
25
  {
26
    id: 3,
27
    date: "Week 4",
28
    title: "Development",
29
    description: "Core features implementation.",
30
  },
31
];
32

33
export default function HorizontalTimelineExample() {
34
  return (
35
    <Timeline
36
      defaultValue={2}
37
      orientation="horizontal"
38
      className="w-full max-w-xl"
39
    >
40
      {releaseCycle.map((item) => (
41
        <TimelineItem key={item.id} step={item.id}>
42
          <TimelineHeader>
43
            <TimelineSeparator />
44
            <TimelineDate>{item.date}</TimelineDate>
45
            <TimelineTitle>{item.title}</TimelineTitle>
46
            <TimelineIndicator />
47
          </TimelineHeader>
48
          <TimelineContent>{item.description}</TimelineContent>
49
        </TimelineItem>
50
      ))}
51
    </Timeline>
52
  );
53
}

With Icons

Forked Repository

Forked the repository to create a new branch for development.15 minutes ago

Pull Request Submitted

Submitted PR #342 with new feature implementation. Waiting for code review.10 minutes ago

Comparing Branches

Received comments on PR. Minor adjustments needed in error handling.5 minutes ago

Merged Branch

Merged the feature branch into the main branch. Ready for deployment.Just now

1
import {
2
  Timeline,
3
  TimelineContent,
4
  TimelineDate,
5
  TimelineHeader,
6
  TimelineIndicator,
7
  TimelineItem,
8
  TimelineSeparator,
9
  TimelineTitle,
10
} from "@/components/ui/pxl/timeline";
11

12
const gitActivity = [
13
  {
14
    id: 1,
15
    date: "15 minutes ago",
16
    title: "Forked Repository",
17
    description:
18
      "Forked the repository to create a new branch for development.",
19
    icon: (
20
      <svg
21
        className="size-3.5"
22
        xmlns="http://www.w3.org/2000/svg"
23
        fill="currentColor"
24
        viewBox="0 0 24 24"
25
      >
26
        <path d="M5 2h4v2H7v2H5V2Zm0 10H3V6h2v6Zm2 2H5v-2h2v2Zm2 2v-2H7v2H3v-2H1v2h2v2h4v4h2v-4h2v-2H9Zm0 0v2H7v-2h2Zm6-12v2H9V4h6Zm4 2h-2V4h-2V2h4v4Zm0 6V6h2v6h-2Zm-2 2v-2h2v2h-2Zm-2 2v-2h2v2h-2Zm0 2h-2v-2h2v2Zm0 0h2v4h-2v-4Z" />
27
      </svg>
28
    ),
29
  },
30
  {
31
    id: 2,
32
    date: "10 minutes ago",
33
    title: "Pull Request Submitted",
34
    description:
35
      "Submitted PR #342 with new feature implementation. Waiting for code review.",
36
    icon: (
37
      <svg
38
        className="size-3.5"
39
        xmlns="http://www.w3.org/2000/svg"
40
        fill="currentColor"
41
        viewBox="0 0 24 24"
42
      >
43
        <path d="M7 12v10H5V12h2Zm13 10h-4v-2h4v2Zm-4-2h-2v-4h2v4Zm6 0h-2v-4h2v4Zm-2-4h-4v-2h4v2ZM8 10H4V8h4v2ZM4 8H2V4h2v4Zm6 0H8V4h2v4Zm7-1h-5V5h5v2ZM8 4H4V2h4v2Z" />
44
      </svg>
45
    ),
46
  },
47
  {
48
    id: 3,
49
    date: "5 minutes ago",
50
    title: "Comparing Branches",
51
    description:
52
      "Received comments on PR. Minor adjustments needed in error handling.",
53
    icon: (
54
      <svg
55
        className="size-3.5"
56
        xmlns="http://www.w3.org/2000/svg"
57
        fill="currentColor"
58
        viewBox="0 0 24 24"
59
      >
60
        <path d="M8 22H4v-2h4v2Zm-4-2H2v-4h2v4Zm6 0H8v-4h2v4Zm7-1h-5v-2h5v2Zm2-2h-2v-5h2v5ZM8 16H4v-2h4v2Zm-1-4H5V2h2v10Zm13-2h-4V8h4v2Zm-4-2h-2V4h2v4Zm6 0h-2V4h2v4Zm-2-4h-4V2h4v2Z" />
61
      </svg>
62
    ),
63
  },
64
  {
65
    id: 4,
66
    date: "Just now",
67
    title: "Merged Branch",
68
    description:
69
      "Merged the feature branch into the main branch. Ready for deployment.",
70
    icon: (
71
      <svg
72
        className="size-3.5"
73
        xmlns="http://www.w3.org/2000/svg"
74
        fill="currentColor"
75
        viewBox="0 0 24 24"
76
      >
77
        <path d="M7 22H5V12h2v10Zm13 0h-4v-2h4v2Zm-4-2h-2v-4h2v4Zm6 0h-2v-4h2v4Zm-2-4h-4v-2h4v2Zm-6-2h-2v-2h2v2Zm-2-2h-2v-2h2v2Zm-4-2H4V8h4v2ZM4 8H2V4h2v4Zm6 0H8V4h2v4ZM8 4H4V2h4v2Z" />
78
      </svg>
79
    ),
80
  },
81
];
82

83
export default function TimelineIconsExample() {
84
  return (
85
    <Timeline defaultValue={3} className="w-full max-w-md">
86
      {gitActivity.map((item) => (
87
        <TimelineItem
88
          key={item.id}
89
          step={item.id}
90
          className="group-data-[orientation=vertical]/timeline:ms-10"
91
        >
92
          <TimelineHeader>
93
            <TimelineSeparator className="group-data-[orientation=vertical]/timeline:-left-7 group-data-[orientation=vertical]/timeline:h-[calc(100%-1.5rem-0.25rem)] group-data-[orientation=vertical]/timeline:translate-y-6.5" />
94
            <TimelineTitle className="mt-0.5">{item.title}</TimelineTitle>
95
            <TimelineIndicator className="bg-foreground/10 group-data-completed/timeline-item:bg-foreground group-data-completed/timeline-item:text-background flex size-6 items-center justify-center border-none group-data-[orientation=vertical]/timeline:-left-7">
96
              {item.icon}
97
            </TimelineIndicator>
98
          </TimelineHeader>
99
          <TimelineContent>
100
            {item.description}
101
            <TimelineDate className="mt-2 mb-0">{item.date}</TimelineDate>
102
          </TimelineContent>
103
        </TimelineItem>
104
      ))}
105
    </Timeline>
106
  );
107
}

With Left-Aligned Dates

Jan 2025

AI Engine Integration

Deep integration of advanced LLMs for real-time code generation and context-aware suggestions.

Feb 2025

Collaborative Editing

Multi-user real-time collaboration with shared cursors and instant synchronization across workspaces.

Mar 2025

Visual Theme Builder

Interactive interface for creating and managing custom design systems with automated CSS variable generation.

Apr 2025

Enterprise Security

Role-based access control, SOC2 compliance audit, and enhanced data encryption protocols.

1
import {
2
  Timeline,
3
  TimelineContent,
4
  TimelineDate,
5
  TimelineHeader,
6
  TimelineIndicator,
7
  TimelineItem,
8
  TimelineSeparator,
9
  TimelineTitle,
10
} from "@/components/ui/pxl/timeline";
11

12
const roadmap = [
13
  {
14
    id: 1,
15
    date: "Jan 2025",
16
    title: "AI Engine Integration",
17
    description:
18
      "Deep integration of advanced LLMs for real-time code generation and context-aware suggestions.",
19
  },
20
  {
21
    id: 2,
22
    date: "Feb 2025",
23
    title: "Collaborative Editing",
24
    description:
25
      "Multi-user real-time collaboration with shared cursors and instant synchronization across workspaces.",
26
  },
27
  {
28
    id: 3,
29
    date: "Mar 2025",
30
    title: "Visual Theme Builder",
31
    description:
32
      "Interactive interface for creating and managing custom design systems with automated CSS variable generation.",
33
  },
34
  {
35
    id: 4,
36
    date: "Apr 2025",
37
    title: "Enterprise Security",
38
    description:
39
      "Role-based access control, SOC2 compliance audit, and enhanced data encryption protocols.",
40
  },
41
];
42

43
export default function LeftAlignedDates() {
44
  return (
45
    <Timeline defaultValue={2} className="w-full max-w-md">
46
      {roadmap.map((item) => (
47
        <TimelineItem
48
          key={item.id}
49
          step={item.id}
50
          className="sm:group-data-[orientation=vertical]/timeline:ms-32"
51
        >
52
          <TimelineHeader>
53
            <TimelineSeparator />
54
            <TimelineDate className="sm:group-data-[orientation=vertical]/timeline:absolute sm:group-data-[orientation=vertical]/timeline:-left-32 sm:group-data-[orientation=vertical]/timeline:w-20 sm:group-data-[orientation=vertical]/timeline:text-right">
55
              {item.date}
56
            </TimelineDate>
57
            <TimelineTitle className="sm:-mt-0.5">{item.title}</TimelineTitle>
58
            <TimelineIndicator />
59
          </TimelineHeader>
60
          <TimelineContent>{item.description}</TimelineContent>
61
        </TimelineItem>
62
      ))}
63
    </Timeline>
64
  );
65
}

Alternating layout

Jan 2024

Seed Funding

Mar 2024

Product MVP

May 2024

First Client

Jul 2024

Series A

Sep 2024

Global Expansion

1
import {
2
  Timeline,
3
  TimelineDate,
4
  TimelineHeader,
5
  TimelineIndicator,
6
  TimelineItem,
7
  TimelineSeparator,
8
  TimelineTitle,
9
} from "@/components/ui/pxl/timeline";
10
import { cn } from "@/lib/utils";
11

12
const milestones = [
13
  {
14
    id: 1,
15
    date: "Jan 2024",
16
    title: "Seed Funding",
17
  },
18
  {
19
    id: 2,
20
    date: "Mar 2024",
21
    title: "Product MVP",
22
  },
23
  {
24
    id: 3,
25
    date: "May 2024",
26
    title: "First Client",
27
  },
28
  {
29
    id: 4,
30
    date: "Jul 2024",
31
    title: "Series A",
32
  },
33
  {
34
    id: 5,
35
    date: "Sep 2024",
36
    title: "Global Expansion",
37
  },
38
];
39

40
export default function TimelineAlternatingExample() {
41
  return (
42
    <Timeline defaultValue={3} className="w-full max-w-md">
43
      {milestones.map((item) => (
44
        <TimelineItem
45
          key={item.id}
46
          step={item.id}
47
          className={cn(
48
            "w-[calc(50%-1.5rem)] odd:ms-auto even:me-auto even:text-right even:group-data-[orientation=vertical]/timeline:ms-0 even:group-data-[orientation=vertical]/timeline:me-8",
49
            "even:group-data-[orientation=vertical]/timeline:**:data-[slot=timeline-indicator]:-right-6 even:group-data-[orientation=vertical]/timeline:**:data-[slot=timeline-indicator]:left-auto",
50
            "even:group-data-[orientation=vertical]/timeline:**:data-[slot=timeline-indicator]:translate-x-1/2 even:group-data-[orientation=vertical]/timeline:**:data-[slot=timeline-separator]:-right-6",
51
            "even:group-data-[orientation=vertical]/timeline:**:data-[slot=timeline-separator]:left-auto even:group-data-[orientation=vertical]/timeline:**:data-[slot=timeline-separator]:translate-x-1/2",
52
          )}
53
        >
54
          <TimelineHeader>
55
            <TimelineSeparator />
56
            <TimelineDate>{item.date}</TimelineDate>
57
            <TimelineTitle>{item.title}</TimelineTitle>
58
            <TimelineIndicator />
59
          </TimelineHeader>
60
        </TimelineItem>
61
      ))}
62
    </Timeline>
63
  );
64
}

API Reference

Timeline

The root component for the timeline.

Prop	Type	Default	Description
`defaultValue`	`number`	`1`	The initial active step.
`value`	`number`	-	The current active step (controlled).
`onValueChange`	`(value: number) => void`	-	Callback fired when the active step changes.
`orientation`	`"horizontal" \| "vertical"`	`"vertical"`	The layout orientation of the timeline.

TimelineItem

A single item in the timeline.

Prop	Type	Default	Description
`step`	`number`	-	Required. The step number for this item.

TimelineDate

The date or time label for a timeline item.

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes for the date label.

TimelineTitle

The title for a timeline item.

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes for the title.

TimelineIndicator

The visual indicator (usually a dot) for a timeline item.

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes for the indicator.

TimelineSeparator

The line connecting timeline indicators.

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes for the separator line.

TimelineHeader

A container for the date and title.

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes for the header container.

TimelineContent

The main descriptive content for a timeline item.

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes for the content container.