Status Timeline

import { Card, CardContent } from "@/components/ui/card"
import {
  StatusTimeline,

Use a status timeline to show where a process stands, such as a transfer, a refund, a card order or an identity check. A thin rail with dots is filled up to the last finished step, and each step can carry a time, a detail and an action. Keep it to about five steps on a card or sheet. Pick a progress bar when only the share done matters, and a list of transactions when the steps are separate events.

Installation#

pnpmnpmyarnbun
pnpm dlx shadcn@latest add @dots/status-timeline
Copy

Usage#

Copyimport {
  StatusTimeline,
  StatusTimelineItem,
} from "@/components/ui/status-timeline"

Copy<StatusTimeline aria-label="Transfer status">
  <StatusTimelineItem status="done" title="Money sent" time="11:44 PM" />
  <StatusTimelineItem status="current" title="Bank is processing" time="Now" />
  <StatusTimelineItem status="pending" title="Received" />
</StatusTimeline>

Composition#

CopyStatusTimeline
└── StatusTimelineItem
    ├── title
    ├── description
    ├── children
    └── time

Features#

• Four statuses: done, current, pending and failed
• A rail filled up to the last finished step
• A cross on a failed step, so it reads without color
• A warning tone for a current step that waits on the user
• The status of each step is read as text by screen readers
• Times as <time> elements when you pass dateTime
• A denser sm size for cards and sheets

Waiting for the user#

Set tone="warning" on the current step when the user has to act, and say so in statusLabel. Put the action in the step's children.

import { Button } from "@/components/ui/button"
import { Card, CardContent } from "@/components/ui/card"
import {

Failed#

Set status="failed" on the step where the process stopped. Use the description for the reason and what to do next.

import { Button } from "@/components/ui/button"
import { Card, CardContent } from "@/components/ui/card"
import {

Small#

Use size="sm" for a denser list inside a card or sheet.

import {
  StatusTimeline,
  StatusTimelineItem,

Accessibility#

StatusTimeline is an ordered list, and the current step has aria-current="step". The dot and the rail are decorative. Each title is followed by its status in visually hidden text: "Completed", "In progress", "Not started" or "Failed".

Name the timeline#

Give the timeline an aria-label that says what process it tracks.

Copy<StatusTimeline aria-label="Refund status">{/* steps */}</StatusTimeline>

Say what is expected#

When a step waits on the user, override the spoken status with statusLabel so it is not just "In progress".

Copy<StatusTimelineItem
  status="current"
  tone="warning"
  statusLabel="Waiting for you"
  title="Selfie needed"
/>

Machine-readable time#

Pass dateTime with an ISO date so the short time is rendered as a <time> element.

API Reference#

StatusTimeline#

The list of steps. Renders an ol and accepts all of its props.

StatusTimelineItem#

One step. Renders an li and accepts all of its props except title.