Advanced Timeline

A robust, multi-layout vertical timeline component for tracking complex events, order statuses, and company histories.

This upgraded TimelineBlock acts as a multi-tool for event visualization. It supports three distinct structural layouts (left, center, and right), embedded action buttons, CSS-grid powered expandable details, and intelligent line-coloring based on item completion statuses.

Each item's status drives its own styling: completed fills the icon and solidifies the line above it, current pulses, and upcoming fades.

Timeline

Each item can carry an icon, a status, an inline action button and expandable content.

Passitems: as the event array — layout="left" is the default rail.

Status Accent Color

Installation

New project? Follow the installation guide to set up Tailwind CSS, shadcn, the cn helper and lucide-react, register the @algorize-ui registry once, then copy your styles from the Themes page.

Install Timeline

npx shadcn@latest add @algorize-ui/timeline

components/custom/blocks/TimelineBlock.tsx is written into your project. Copy any snippet from a Usage tab above and it runs.

Install dependencies

Nothing beyond the shared setup — Timeline needs only the cn helper and lucide-react, which the installation guide already put in place.

Requires Tailwind CSS v4

The breakpoints are container queries (@container/timeline, @container/tlcard) rather than media queries, so the rail reacts to the width of the column it is dropped into instead of the width of the window — a timeline in a 600px sidebar behaves the same whether the browser is 800px or 2560px wide. Container queries are built into Tailwind v4; on v3 the rail will not respond.

Examples

Center layout

Setlayout"center": to alternate cards either side of the rail. It folds back to one column below 576px — and that is a container query, so it tracks the column the timeline sits in, not the window.

Right layout

Setlayout"right": to mirror the left rail.

Minimal

Setvariant"minimal": to remove the card chrome for a lighter feed — the rail and type carry the structure.

Glass

Setvariant"glass": to frost the cards; put something behind them.

Without the entrance

Setanimate{false}: to skip the staggered entrance — right for content that is already on screen.

Props Reference

Component	Prop	Type	Default	Description
`TimelineBlock`	`items`	`TimelineItemType[]`	Required	An array of configuration objects representing each event on the timeline. See the TimelineItemType reference below.
`TimelineBlock`	`layout`	`"left" \| "center" \| "right"`	`"left"`	Determines the structural alignment of the timeline. Using `center` creates an alternating zig-zag layout on desktop and elegantly falls back to left-aligned on mobile.
`TimelineBlock`	`variant`	`"default" \| "minimal" \| "glass"`	`"default"`	Determines the architectural style of the event cards, backgrounds, and the vertical tracking line.
`TimelineBlock`	`color`	`"indigo" \| "rose" \| "emerald" \| "zinc" \| string`	`"primary"`	The dynamic accent color applied to completed/current tracking lines, glowing nodes, and hover states. Fully supports custom hex codes.
`TimelineBlock`	`animate`	`boolean`	`true`	If true, the timeline nodes will execute a staggered fade-and-slide entry animation (Web Animations API, no library) when the component mounts.

TimelineItemType Object

Object	Property	Type	Default	Description
`TimelineItemType`	`id`	`string \| number`	Required	A unique identifier for the event. Used internally for React keys and handling the expansion state safely.
`TimelineItemType`	`title`	`string`	Required	The primary headline for the specific timeline event.
`TimelineItemType`	`date`	`string`	Required	The timestamp, date string, or status badge displayed inside the event header.
`TimelineItemType`	`status`	`"completed" \| "current" \| "upcoming"`	`"completed"`	Drives the visual styling. `completed` fills the vertical line, `current` adds a pulsing glow, and `upcoming` fades the node out.
`TimelineItemType`	`description`	`string`	`undefined`	An optional secondary text string displayed directly beneath the title.
`TimelineItemType`	`icon`	`React.ElementType`	`undefined`	An optional Lucide (or custom SVG) icon to render inside the circular indicator node. If omitted, a clean solid dot is used.
`TimelineItemType`	`content`	`ReactNode`	`undefined`	If provided, the entire event header becomes a clickable trigger that smoothly expands to reveal this detailed content.
`TimelineItemType`	`action`	`ReactNode`	`undefined`	An optional slot for rendering buttons, links, or specific badges immediately below the header area.