Timeline

A vertical timeline — a display-only component of markers, connector lines, times, titles and descriptions

Installation

$npx litefy@latest add timeline
$pnpm dlx litefy@latest add timeline
$yarn dlx litefy@latest add timeline
$bun --bun litefy@latest add timeline

Usage

A display-only component with no controlled state — entries are defined via items, and the connector line automatically stops at the last entry.

2026-08-30 10:24Order placedOrder #1042 created from web checkout
2026-08-30 14:02Payment confirmedVisa ···· 4242 charged $86.00
2026-08-31 09:40ShippedPackage handed to carrier SF-EX
2026-08-31 18:15Delivered

"use client";

import { Timeline } from "@/ui";

const items = [
  {
    time: "2026-08-30 10:24",
    heading: "Order placed",
    description: "Order #1042 created from web checkout", // design-detect-disable-line hardcoded-color（文案里的订单号，不是色值）
  },
  {
    time: "2026-08-30 14:02",
    heading: "Payment confirmed",
    description: "Visa ···· 4242 charged $86.00",
  },
  {
    time: "2026-08-31 09:40",
    heading: "Shipped",
    description: "Package handed to carrier SF-EX",
  },
  {
    time: "2026-08-31 18:15",
    heading: "Delivered",
  },
];

export default function TimelineBasicDemo() {
  return <Timeline items={items} className="max-w-sm" />;
}

Custom Marker

Pass any node — commonly a lucide icon — as marker to replace the default dot.

2026-08-30 10:24Order placedOrder #1042 created from web checkout
2026-08-30 14:02Payment confirmedVisa ···· 4242 charged $86.00
2026-08-31 09:40ShippedPackage handed to carrier SF-EX
2026-08-31 18:15Delivered

"use client";

import { CircleCheck, CreditCard, Package, ShoppingCart } from "lucide-react";
import { Timeline } from "@/ui";

const items = [
  {
    marker: <ShoppingCart className="size-3" />,
    time: "2026-08-30 10:24",
    heading: "Order placed",
    description: "Order #1042 created from web checkout", // design-detect-disable-line hardcoded-color（文案里的订单号，不是色值）
  },
  {
    marker: <CreditCard className="size-3" />,
    time: "2026-08-30 14:02",
    heading: "Payment confirmed",
    description: "Visa ···· 4242 charged $86.00",
  },
  {
    marker: <Package className="size-3" />,
    time: "2026-08-31 09:40",
    heading: "Shipped",
    description: "Package handed to carrier SF-EX",
  },
  {
    marker: <CircleCheck className="size-3 text-success" />,
    time: "2026-08-31 18:15",
    heading: "Delivered",
  },
];

export default function TimelineMarkerDemo() {
  return <Timeline items={items} className="max-w-sm" />;
}

API Reference

Prop	Type	Default	Description
`items`	`TimelineItemConfig[]`	-	Timeline entry definitions
`className`	`ClassNameValue`	-	Custom class names, applied to the root
`classNames`	`marker` / `connector` / `time` / `heading` / `description`	-	Custom class names per slot

TimelineItemConfig

Field	Type	Default	Description
`marker`	`React.ReactNode`	-	Optional custom marker content (e.g. an icon), defaults to a primary dot
`time`	`React.ReactNode`	-	Optional time text
`heading`	`React.ReactNode`	-	Entry title
`description`	`React.ReactNode`	-	Optional description text

Composable Components

The parts extend native DOM props and merge their built-in className through cn — passing className extends the defaults instead of replacing them.

TimelineRoot

The outer <ol> flex container (list semantics come from the native element).

Prop	Type	Default	Description
`className`	`ClassNameValue`	-	Custom class names
`...props`	`React.ComponentProps<"ol">`	-	Native ol props

TimelineItem

A single entry: marker, connector line (controlled by connector), time, title and optional description.

Prop	Type	Default	Description
`connector`	`boolean`	`true`	Whether to render the connector below the marker
`marker`	`React.ReactNode`	-	Optional custom marker content, defaults to a primary dot
`time`	`React.ReactNode`	-	Optional time text
`heading`	`React.ReactNode`	-	Entry title
`description`	`React.ReactNode`	-	Optional description text
`className`	`ClassNameValue`	-	Custom class names, applied to the item
`classNames`	`marker` / `connector` / `time` / `heading` / `description`	-	Custom class names per slot
`...props`	`React.ComponentProps<"li">`	-	Native li props

Timeline

On this page