308

Timeline

PreviousNext

Timeline displays a list of events in chronological order.

  1. Eat
    Because you need strength
  2. Code
    Because it's awesome!
  3. Sleep
    Because you need rest
  4. Repeat
    Because this is the life you love!
import {
  Timeline,
  TimelineConnector,

Installation

pnpm dlx shadcn@latest add junwen-k/ui-x/timeline

Usage

import {
  Timeline,
  TimelineConnector,
  TimelineContent,
  TimelineDescription,
  TimelineDot,
  TimelineItem,
  TimelineSeparator,
  TimelineTitle,
} from "@/components/ui/timeline";
<Timeline>
  <TimelineItem>
    <TimelineSeparator>
      <TimelineDot />
      <TimelineConnector />
    </TimelineSeparator>
    <TimelineContent>
      <TimelineTitle>Eat</TimelineTitle>
      <TimelineDescription>Because you need strength</TimelineDescription>
    </TimelineContent>
  </TimelineItem>
  <TimelineItem>
    <TimelineSeparator>
      <TimelineDot />
      <TimelineConnector />
    </TimelineSeparator>
    <TimelineContent>
      <TimelineTitle>Code</TimelineTitle>
      <TimelineDescription>Because it's awesome!</TimelineDescription>
    </TimelineContent>
  </TimelineItem>
  <TimelineItem>
    <TimelineSeparator>
      <TimelineDot />
      <TimelineConnector />
    </TimelineSeparator>
    <TimelineContent>
      <TimelineTitle>Sleep</TimelineTitle>
      <TimelineDescription>Because you need rest</TimelineDescription>
    </TimelineContent>
  </TimelineItem>
  <TimelineItem>
    <TimelineSeparator>
      <TimelineDot />
    </TimelineSeparator>
    <TimelineContent>
      <TimelineTitle>Repeat</TimelineTitle>
      <TimelineDescription>
        Because this is the life you love!
      </TimelineDescription>
    </TimelineContent>
  </TimelineItem>
</Timeline>

Examples

Default

  1. Eat
    Because you need strength
  2. Code
    Because it's awesome!
  3. Sleep
    Because you need rest
  4. Repeat
    Because this is the life you love!
import {
  Timeline,
  TimelineConnector,

Alternate

  1. Eat
    Because you need strength
  2. Code
    Because it's awesome!
  3. Sleep
    Because you need rest
  4. Repeat
    Because this is the life you love!
import {
  Timeline,
  TimelineConnector,

With Icon

  1. Eat
    Because you need strength
  2. Code
    Because it's awesome!
  3. Sleep
    Because you need rest
  4. Repeat
    Because this is the life you love!
import { Code, Heart, Moon, Pizza } from "lucide-react";

import {

Horizontal

  1. Ordered
    9.15 AM, January 1, 2024
  2. Shipped
    12:20 PM, January 4, 2024
  3. Out for Delivery
    07:00 AM, January 8, 2024
import { PackageCheck, ShoppingCart, Truck } from "lucide-react";

import {

Accessibility

The timeline renders an ordered list (<ol role="list">), so assistive technology announces the number of events and their order. Dots and connectors are purely visual — keep the meaning of each event in its TimelineTitle and TimelineDescription text rather than in the dot's color or icon alone.

API Reference

Timeline

The list container. Renders an <ol>.

PropTypeDefaultDescription
orientation"horizontal" | "vertical""vertical"The layout direction of the timeline.
...propsReact.ComponentProps<"ol">-Props spread to the list element.

TimelineItem

A single event. Renders an <li>.

PropTypeDefaultDescription
renderReactElement | function-Render as a different element.
...propsReact.ComponentProps<"li">-Props spread to the item element.

TimelineSeparator

Lays out the dot and connector alongside the content. Renders a <div>.

PropTypeDefaultDescription
renderReactElement | function-Render as a different element.
...propsReact.ComponentProps<"div">-Props spread to the separator element.

TimelineDot

The event marker. Renders a <div> showing a dot while empty; place an icon inside to replace it.

PropTypeDefaultDescription
variant"default" | "outline""default"Filled or outlined dot when rendered empty.
renderReactElement | function-Render as a different element.
...propsReact.ComponentProps<"div">-Props spread to the dot element.

TimelineConnector

The line connecting one event to the next. Renders a <div>; omit it on the last item.

PropTypeDefaultDescription
renderReactElement | function-Render as a different element.
...propsReact.ComponentProps<"div">-Props spread to the connector element.

TimelineContent, TimelineTitle, TimelineDescription

The event's content, heading text and supporting text. Each renders a <div> and supports the render prop.

useTimeline

Hook exposing the timeline context (orientation) for building custom parts. Must be used within <Timeline />.