Timeline

timeline

Orders events along a timeline with colored or custom markers, alternate placement, and a pending state.

Usage

Basic usage

items array driver, each item label is used as the timestamp, children is used as the text, and color controls the dot tone.

Employee submits reimbursement application
09:12
Approved by the direct manager
10:40
Financial review returned (missing invoice)
14:05
Employee supplements materials and resubmits
16:20

tsx

<Timeline
  items={[
    { label: "09:12", children: "Employee submits reimbursement application", color: "primary" },
    { label: "10:40", children: "Approved by the direct manager", color: "success" },
    { label: "14:05", children: "Financial review returned (missing invoice)", color: "danger" },
    { label: "16:20", children: "Employee supplements materials and resubmits", color: "warning" },
  ]}
/>

In progress (pending)

pending Append the ongoing ghost item at the end (loading dot + dotted line connected).

The package has been collected · Hangzhou Transshipment Center
06-01 08:00
In transit · Sent to Shanghai
06-01 22:30
Arrived at Shanghai Pudong delivery point
06-02 09:15
In transit · Estimated delivery tomorrow

tsx

<Timeline items={logistics} pending="In transit·Estimated delivery tomorrow" />

Custom node

The compound usage is directly transferred to <TimelineItem>, dot can be replaced by an icon (use currentColor to color with color).

Account registration completed
Step 1
Real-name authentication passed
Step 2
Binding payment account (in progress)
Step 3

tsx

<Timeline>
  <TimelineItem label="Step 1" color="success" dot={CheckIcon}>Account registration completed</TimelineItem>
  <TimelineItem label="Step 2" color="success" dot={CheckIcon}>Real-name authentication passed</TimelineItem>
  <TimelineItem label="Step 3" color="primary">Bind the collection account (in progress)</TimelineItem>
</Timeline>

Layout direction

mode Control node location: left (default) / right mirror / alternate left and right.

The package has been collected · Hangzhou Transshipment Center
06-01 08:00
In transit · Sent to Shanghai
06-01 22:30
Arrived at Shanghai Pudong delivery point
06-02 09:15

Employee submits reimbursement application
09:12
Approved by the direct manager
10:40
Financial review returned (missing invoice)
14:05
Employee supplements materials and resubmits
16:20

tsx

<>
  <Timeline items={logistics} mode="right" />
  <Timeline items={approval} mode="alternate" />
</>

When to use

Use Timeline for chronological approvals, shipment tracking, or activity history. Use GitCommit for one commit reference or Steps for a user-progressed sequence.

Import

import { Timeline, TimelineItem } from "@hulianui/ui"

Props

Timeline

Name	Type	Default	Description
items	`TimelineItemProps[]`	—	Data-driven items equivalent to `<TimelineItem {...item} />`; exclusive with children.
mode	`"left" \| "right" \| "alternate"`	`"left"`	Left nodes, mirrored right nodes, or alternating content around a center line.
…HTMLAttributes	`Omit<HTMLAttributes<HTMLOListElement>, "children">`	—	Forwarded ordered-list attributes.

TimelineItem

Name	Type	Default	Description
color	`"default" \| "primary" \| "success" \| "danger" \| "warning"`	`"default"`	Default dot tone; ignored with a custom dot.
pending	`boolean`	`false`	Shows a spinning pending ring and makes the incoming connector dashed.
className	`string`	—	Custom class name.

Slots

Timeline

Slot	Type	Description
children	`ReactNode`	Compound TimelineItem children; exclusive with items.
pending	`boolean \| ReactNode`	Appends a pending ghost item; true shows only the spinner, or supply content.

TimelineItem

Slot	Type	Description
children	`ReactNode`	Primary event content.
dot	`ReactNode`	Custom node such as an icon, replacing the colored dot.
label	`ReactNode`	Muted timestamp or metadata below the main content.

Pitfalls

Choose items or children, not both.
label is secondary metadata below the body; do not place primary content there.
A custom dot replaces the default dot and makes color ineffective.

Stat · Statistic · Chart · Meter · NumberTicker · WorldMap

Playground

Layout directionEnding in progress

Employee submits reimbursement application
09:12
Approved by the direct manager
10:40
Financial review returned (missing invoice)
14:05
Employee supplements materials and resubmits
16:20

<Timeline items={items} />

Usage

Basic usage

items array driver, each item label is used as the timestamp, children is used as the text, and color controls the dot tone.

Employee submits reimbursement application
09:12
Approved by the direct manager
10:40
Financial review returned (missing invoice)
14:05
Employee supplements materials and resubmits
16:20

tsx

<Timeline
  items={[
    { label: "09:12", children: "Employee submits reimbursement application", color: "primary" },
    { label: "10:40", children: "Approved by the direct manager", color: "success" },
    { label: "14:05", children: "Financial review returned (missing invoice)", color: "danger" },
    { label: "16:20", children: "Employee supplements materials and resubmits", color: "warning" },
  ]}
/>

In progress (pending)

pending Append the ongoing ghost item at the end (loading dot + dotted line connected).

The package has been collected · Hangzhou Transshipment Center
06-01 08:00
In transit · Sent to Shanghai
06-01 22:30
Arrived at Shanghai Pudong delivery point
06-02 09:15
In transit · Estimated delivery tomorrow

tsx

<Timeline items={logistics} pending="In transit·Estimated delivery tomorrow" />

Custom node

The compound usage is directly transferred to <TimelineItem>, dot can be replaced by an icon (use currentColor to color with color).

Account registration completed
Step 1
Real-name authentication passed
Step 2
Binding payment account (in progress)
Step 3

tsx

<Timeline>
  <TimelineItem label="Step 1" color="success" dot={CheckIcon}>Account registration completed</TimelineItem>
  <TimelineItem label="Step 2" color="success" dot={CheckIcon}>Real-name authentication passed</TimelineItem>
  <TimelineItem label="Step 3" color="primary">Bind the collection account (in progress)</TimelineItem>
</Timeline>

Layout direction

mode Control node location: left (default) / right mirror / alternate left and right.

The package has been collected · Hangzhou Transshipment Center
06-01 08:00
In transit · Sent to Shanghai
06-01 22:30
Arrived at Shanghai Pudong delivery point
06-02 09:15

Employee submits reimbursement application
09:12
Approved by the direct manager
10:40
Financial review returned (missing invoice)
14:05
Employee supplements materials and resubmits
16:20

tsx

<>
  <Timeline items={logistics} mode="right" />
  <Timeline items={approval} mode="alternate" />
</>

Props

Timeline

Name	Type	Default	Description
items	`TimelineItemProps[]`	—	Data-driven items equivalent to `<TimelineItem {...item} />`; exclusive with children.
mode	`"left" \| "right" \| "alternate"`	`"left"`	Left nodes, mirrored right nodes, or alternating content around a center line.
…HTMLAttributes	`Omit<HTMLAttributes<HTMLOListElement>, "children">`	—	Forwarded ordered-list attributes.

TimelineItem

Name	Type	Default	Description
color	`"default" \| "primary" \| "success" \| "danger" \| "warning"`	`"default"`	Default dot tone; ignored with a custom dot.
pending	`boolean`	`false`	Shows a spinning pending ring and makes the incoming connector dashed.
className	`string`	—	Custom class name.

Slots

Timeline

Slot	Type	Description
children	`ReactNode`	Compound TimelineItem children; exclusive with items.
pending	`boolean \| ReactNode`	Appends a pending ghost item; true shows only the spinner, or supply content.

TimelineItem

Slot	Type	Description
children	`ReactNode`	Primary event content.
dot	`ReactNode`	Custom node such as an icon, replacing the colored dot.
label	`ReactNode`	Muted timestamp or metadata below the main content.

Timeline

Usage

Basic usage

In progress (pending)

Custom node

Layout direction

When to use

Import

Props

Timeline

TimelineItem

Slots

Timeline

TimelineItem

Pitfalls

Related

Playground

Timeline

Usage

Basic usage

In progress (pending)

Custom node

Layout direction

When to use

Import

Props

Timeline

TimelineItem

Slots

Timeline

TimelineItem

Pitfalls

Related

Playground