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

Basic 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",
  },
  {
    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" />;
}

Key points:

Each entry renders time (tabular numerals), heading (medium weight) and optional description (muted text) top to bottom — all React.ReactNode.
The marker defaults to a primary-colored dot; passing marker (e.g. an icon) automatically enlarges it into a bordered circular container.
The connector line is managed by Timeline: the last entry renders none; when using TimelineItem standalone, turn it off via connector={false}.

API Reference

Timeline

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