Timeline item

Pro

A list of things that happened, in order, on an icon rail: each item's icon in a ring on a line that joins them, on the inline-start side. The rail and rings are borders, so they stay drawn in forced colours.

For events inside a chat thread use ThreadEvent; for a document's saved versions, VersionHistory. Timeline is for any other history: a record's activity, an incident's steps, an order's progress.

Markdown

Version 5.2.0· other versions

This page is for 5.2.0, the current release. An earlier release’s page is the Markdown that release published, so the docs match the version you have installed (candor-lock.json records it).

Not in the docs of 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.6.0, 1.7.0, 1.8.0, 1.8.1, 1.9.0, 1.9.1, 2.0.0, 2.1.0, 2.2.0, 2.3.0, 2.4.0, 2.5.0, 2.5.1, 2.6.0, 2.6.1, 2.6.2, 2.7.0, 2.8.0, 2.9.0, 2.10.0, 3.0.0, 4.0.0, 4.0.1, 4.0.2, 4.1.0 and 4.2.0: the page came later, or had another name then.

Docs pages weren’t kept for 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0 and 1.2.1: they are kept from 1.3.0 on, and before that only llms.txt was published.

Preview

Install

With the Candor CLI

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/timeline-item

Brings in: bidi, locale, relative-time, tokens, utils · npm: lucide-react@^1.67.0

Usage

TSX · The example above

"use client"

import { Bot, MessageSquare } from "lucide-react"
import { Timeline, TimelineItem } from "@/components/candor/timeline-item"

const minutes = (n: number) => new Date(Date.now() - n * 60_000)

export default function Example() {
  return (
    <div className="max-w-md rounded-xl border bg-card p-4">
      <Timeline label="Activity on refund R-2041">
        <TimelineItem title="Asked for a refund" icon={MessageSquare} actor="Dana Reyes" time={minutes(95)}>
          The order arrived damaged.
        </TimelineItem>
        <TimelineItem title="Checked the order against the refund policy" icon={Bot} actor="Billing agent" time={minutes(94)} />
        <TimelineItem title="Refund over the agent's limit" tone="warning" actor="Billing agent" time={minutes(94)}>
          Sent to a person to approve.
        </TimelineItem>
        <TimelineItem title="Approved the refund" tone="success" actor="Sam Okafor" time={minutes(12)} />
        <TimelineItem title="Card network confirmation" tone="muted" time={null} />
      </Timeline>
    </div>
  )
}

<Timeline>

Prop	Type	Default	Description
label	`string \| undefined`	—	The list's accessible name ("Activity on Q3 report").
className	`string \| undefined`	—	Classes for the list, merged with Candor's.
children	`React.ReactNode \| undefined`	—	The `TimelineItem`s, in the order they happened (or newest first, as the app chooses).

<TimelineItem>

One thing that happened in a Timeline: an icon in a ring, a title, who did it and when, and a body. The tone's icon carries its meaning (a tick, a warning sign, a cross) and the colour repeats it, never alone; screen readers hear it as a word before the title ("Done", "Warning", "Failed", from timelineItem in LocaleProvider's strings). icon replaces the tone's icon, not its word. "default" and "muted" have no word. title can be an agent's words, so it is drawn as text in its own isolate. actor is named by the app. A time of null says "Time not recorded" rather than leaving the reader to guess.

Prop	Type	Default	Description
icon	`LucideIcon \| undefined`	—	The item's icon, in place of the tone's own. Shape, not colour, should say what it is.
tone	`TimelineTone \| undefined`	"default"	How it reads: "default", "success", "warning", "destructive" or "muted". Colours the ring and the icon.
titlerequired	`string`	—	What happened ("Approved the refund"). Drawn as text, so it can be an agent's words.
time	`string \| Date \| null \| undefined`	—	When it happened, relative with the full date on hover; `null` says "Time not recorded". Left out, no time is shown.
actor	`string \| undefined`	—	Who did it, named by the app (a person, or the agent by its app-given name).
children	`React.ReactNode \| undefined`	—	The body: details, a quote, a link to the record.
className	`string \| undefined`	—	Classes for the item, merged with Candor's.

Strings

The fixed words, in English by default. Change any of them under timelineItem in <LocaleProvider strings={{ … }}>; the table is exported as timelineItemStrings.

Key	English
noTime	Time not recorded
success	Done
warning	Warning
destructive	Failed

Types

TimelineTone: How an item reads at a glance; the icon carries it, the colour only repeats it.; "default" | "success" | "warning" | "destructive" | "muted"