Skip to content

Pro pre-sale is open. Installation opens January 2027. See Pro

werewolf-ui
Components

Timeline

An ordered list of events, such as the steps of an agent run or the history of an order: each event has a marker (a dot, an icon or an avatar) colored by its status, a connector line to the next one, a title, a time, a description and any content. Vertical by default, or horizontal in a row.

  • npm: 0 direct, 1 total
  • registry: 2 direct, 2 total

Preview

  1. Searched the docs
    done

    Found 4 pages about tokens.

  2. Read tokens.css
    done

    312 lines, 48 color tokens.

  3. Writing the answer
    in progress

    The current step.

Props

  • orientation
  • size
  • scrollLabel
  • marker
  • descriptions
import { IconFileText, IconLoader2, IconSearch } from "@tabler/icons-react"
import { Timeline, TimelineItem } from "@/components/ui/timeline"

<Timeline>
  <TimelineItem status="success" icon={<IconSearch />} title="Searched the docs" time="10:42" dateTime="2026-10-24T10:42" description="Found 4 pages about tokens." />
  <TimelineItem status="success" icon={<IconFileText />} title="Read tokens.css" time="10:43" dateTime="2026-10-24T10:43" description="312 lines, 48 color tokens." />
  <TimelineItem status="info" icon={<IconLoader2 />} title="Writing the answer" time="10:43" dateTime="2026-10-24T10:43" description="The current step." current />
</Timeline>

Usage

When to use

  • Show events in the order they happened, such as the steps of an agent run, a deploy or the history of an order.
  • An activity feed where each entry says who did what and when.

When not to use

  • Steps of a flow the user moves through. Use Stepper.
  • A list of items with no order in time. Use a list or Table.
  • A single status. Use Badge or Alert.

Variants

orientation

vertical stacks events down the page; horizontal lays them out in equal columns that scroll sideways when narrow.

    1. Searched the docs
      done

      Found 4 pages about tokens.

    2. Read tokens.css
      done

      312 lines, 48 color tokens.

    3. Writing the answer
      in progress

      The current step.

    verticaldefault

    1. Searched the docs
      done

      Found 4 pages about tokens.

    2. Read tokens.css
      done

      312 lines, 48 color tokens.

    3. Writing the answer
      in progress

      The current step.

    horizontal

import { IconFileText, IconLoader2, IconSearch } from "@tabler/icons-react"
import { Timeline, TimelineItem } from "@/components/ui/timeline"

<Timeline>
  <TimelineItem status="success" icon={<IconSearch />} title="Searched the docs" time="10:42" dateTime="2026-10-24T10:42" description="Found 4 pages about tokens." />
  <TimelineItem status="success" icon={<IconFileText />} title="Read tokens.css" time="10:43" dateTime="2026-10-24T10:43" description="312 lines, 48 color tokens." />
  <TimelineItem status="info" icon={<IconLoader2 />} title="Writing the answer" time="10:43" dateTime="2026-10-24T10:43" description="The current step." current />
</Timeline>
<Timeline orientation="horizontal">
  <TimelineItem status="success" icon={<IconSearch />} title="Searched the docs" time="10:42" dateTime="2026-10-24T10:42" description="Found 4 pages about tokens." />
  <TimelineItem status="success" icon={<IconFileText />} title="Read tokens.css" time="10:43" dateTime="2026-10-24T10:43" description="312 lines, 48 color tokens." />
  <TimelineItem status="info" icon={<IconLoader2 />} title="Writing the answer" time="10:43" dateTime="2026-10-24T10:43" description="The current step." current />
</Timeline>

size

Marker box, text and spacing: 24, 32 or 40px markers.

    1. Searched the docs
      done

      Found 4 pages about tokens.

    2. Read tokens.css
      done

      312 lines, 48 color tokens.

    3. Writing the answer
      in progress

      The current step.

    sm

    1. Searched the docs
      done

      Found 4 pages about tokens.

    2. Read tokens.css
      done

      312 lines, 48 color tokens.

    3. Writing the answer
      in progress

      The current step.

    mddefault

    1. Searched the docs
      done

      Found 4 pages about tokens.

    2. Read tokens.css
      done

      312 lines, 48 color tokens.

    3. Writing the answer
      in progress

      The current step.

    lg

import { IconFileText, IconLoader2, IconSearch } from "@tabler/icons-react"
import { Timeline, TimelineItem } from "@/components/ui/timeline"

<Timeline size="sm">
  <TimelineItem status="success" icon={<IconSearch />} title="Searched the docs" time="10:42" dateTime="2026-10-24T10:42" description="Found 4 pages about tokens." />
  <TimelineItem status="success" icon={<IconFileText />} title="Read tokens.css" time="10:43" dateTime="2026-10-24T10:43" description="312 lines, 48 color tokens." />
  <TimelineItem status="info" icon={<IconLoader2 />} title="Writing the answer" time="10:43" dateTime="2026-10-24T10:43" description="The current step." current />
</Timeline>
<Timeline>
  <TimelineItem status="success" icon={<IconSearch />} title="Searched the docs" time="10:42" dateTime="2026-10-24T10:42" description="Found 4 pages about tokens." />
  <TimelineItem status="success" icon={<IconFileText />} title="Read tokens.css" time="10:43" dateTime="2026-10-24T10:43" description="312 lines, 48 color tokens." />
  <TimelineItem status="info" icon={<IconLoader2 />} title="Writing the answer" time="10:43" dateTime="2026-10-24T10:43" description="The current step." current />
</Timeline>
<Timeline size="lg">
  <TimelineItem status="success" icon={<IconSearch />} title="Searched the docs" time="10:42" dateTime="2026-10-24T10:42" description="Found 4 pages about tokens." />
  <TimelineItem status="success" icon={<IconFileText />} title="Read tokens.css" time="10:43" dateTime="2026-10-24T10:43" description="312 lines, 48 color tokens." />
  <TimelineItem status="info" icon={<IconLoader2 />} title="Writing the answer" time="10:43" dateTime="2026-10-24T10:43" description="The current step." current />
</Timeline>

status

On TimelineItem. Colors the marker from the status tokens.

    1. Searched the docs
      done

      Found 4 pages about tokens.

    2. Read tokens.css
      done

      312 lines, 48 color tokens.

    3. Writing the answer
      in progress

      The current step.

    defaultdefault

    1. Searched the docs
      done

      Found 4 pages about tokens.

    2. Read tokens.css
      done

      312 lines, 48 color tokens.

    3. Writing the answer
      in progress

      The current step.

    success

    1. Searched the docs
      done

      Found 4 pages about tokens.

    2. Read tokens.css
      done

      312 lines, 48 color tokens.

    3. Writing the answer
      in progress

      The current step.

    warning

    1. Searched the docs
      done

      Found 4 pages about tokens.

    2. Read tokens.css
      done

      312 lines, 48 color tokens.

    3. Writing the answer
      in progress

      The current step.

    danger

    1. Searched the docs
      done

      Found 4 pages about tokens.

    2. Read tokens.css
      done

      312 lines, 48 color tokens.

    3. Writing the answer
      in progress

      The current step.

    info

import { IconFileText, IconLoader2, IconSearch } from "@tabler/icons-react"
import { Timeline, TimelineItem } from "@/components/ui/timeline"

<Timeline>
  <TimelineItem status="success" icon={<IconSearch />} title="Searched the docs" time="10:42" dateTime="2026-10-24T10:42" description="Found 4 pages about tokens." />
  <TimelineItem status="success" icon={<IconFileText />} title="Read tokens.css" time="10:43" dateTime="2026-10-24T10:43" description="312 lines, 48 color tokens." />
  <TimelineItem status="info" icon={<IconLoader2 />} title="Writing the answer" time="10:43" dateTime="2026-10-24T10:43" description="The current step." current />
</Timeline>
<Timeline status="success">
  <TimelineItem status="success" icon={<IconSearch />} title="Searched the docs" time="10:42" dateTime="2026-10-24T10:42" description="Found 4 pages about tokens." />
  <TimelineItem status="success" icon={<IconFileText />} title="Read tokens.css" time="10:43" dateTime="2026-10-24T10:43" description="312 lines, 48 color tokens." />
  <TimelineItem status="info" icon={<IconLoader2 />} title="Writing the answer" time="10:43" dateTime="2026-10-24T10:43" description="The current step." current />
</Timeline>
<Timeline status="warning">
  <TimelineItem status="success" icon={<IconSearch />} title="Searched the docs" time="10:42" dateTime="2026-10-24T10:42" description="Found 4 pages about tokens." />
  <TimelineItem status="success" icon={<IconFileText />} title="Read tokens.css" time="10:43" dateTime="2026-10-24T10:43" description="312 lines, 48 color tokens." />
  <TimelineItem status="info" icon={<IconLoader2 />} title="Writing the answer" time="10:43" dateTime="2026-10-24T10:43" description="The current step." current />
</Timeline>
<Timeline status="danger">
  <TimelineItem status="success" icon={<IconSearch />} title="Searched the docs" time="10:42" dateTime="2026-10-24T10:42" description="Found 4 pages about tokens." />
  <TimelineItem status="success" icon={<IconFileText />} title="Read tokens.css" time="10:43" dateTime="2026-10-24T10:43" description="312 lines, 48 color tokens." />
  <TimelineItem status="info" icon={<IconLoader2 />} title="Writing the answer" time="10:43" dateTime="2026-10-24T10:43" description="The current step." current />
</Timeline>
<Timeline status="info">
  <TimelineItem status="success" icon={<IconSearch />} title="Searched the docs" time="10:42" dateTime="2026-10-24T10:42" description="Found 4 pages about tokens." />
  <TimelineItem status="success" icon={<IconFileText />} title="Read tokens.css" time="10:43" dateTime="2026-10-24T10:43" description="312 lines, 48 color tokens." />
  <TimelineItem status="info" icon={<IconLoader2 />} title="Writing the answer" time="10:43" dateTime="2026-10-24T10:43" description="The current step." current />
</Timeline>

Examples

Agent run

Icons in soft status circles for the steps of a run, with the current step marked.

  1. Searched the docs
    done

    Found 4 pages about tokens.

  2. Read tokens.css10:43
    done
  3. Writing the answer10:43
    in progress
import { IconFileText, IconLoader2, IconSearch } from "@tabler/icons-react"
import { Timeline, TimelineItem } from "@/components/ui/timeline"

<Timeline>
  <TimelineItem status="success" icon={<IconSearch />} title="Searched the docs" time="10:42" dateTime="2026-10-24T10:42" description="Found 4 pages about tokens." />
  <TimelineItem status="success" icon={<IconFileText />} title="Read tokens.css" time="10:43" />
  <TimelineItem status="info" icon={<IconLoader2 />} title="Writing the answer" time="10:43" current />
</Timeline>

Order history

Dots colored by status, with a description under each event.

  1. DeliveredOct 24
    done

    Left at the front desk.

  2. Delivery delayedOct 23
    needs attention

    Weather on the route.

  3. ShippedOct 21
  4. Order placedOct 20
import { Timeline, TimelineItem } from "@/components/ui/timeline"

<Timeline>
  <TimelineItem status="success" title="Delivered" time="Oct 24" description="Left at the front desk." />
  <TimelineItem status="warning" title="Delivery delayed" time="Oct 23" description="Weather on the route." />
  <TimelineItem title="Shipped" time="Oct 21" />
  <TimelineItem title="Order placed" time="Oct 20" />
</Timeline>

Statuses

Each status colors the dot (solid) or the icon circle (soft) from its status tokens.

  1. Default09:00
  2. Success09:05
    done
  3. Warning09:10
    needs attention
  4. Danger09:15
    failed
  5. Info09:20
    in progress
import { Timeline, TimelineItem } from "@/components/ui/timeline"

<Timeline>
  <TimelineItem title="Default" time="09:00" />
  <TimelineItem status="success" title="Success" time="09:05" />
  <TimelineItem status="warning" title="Warning" time="09:10" />
  <TimelineItem status="danger" title="Danger" time="09:15" />
  <TimelineItem status="info" title="Info" time="09:20" />
</Timeline>

Activity with avatars

An avatar marker shows who acted; content holds anything under the description.

  1. Linh commented2 hours ago
    Can we keep the old name for one release?
  2. An opened the pull requestYesterday
import { Avatar } from "@/components/ui/avatar"
import { Card } from "@/components/ui/card"
import { Timeline, TimelineItem } from "@/components/ui/timeline"

<Timeline>
  <TimelineItem avatar={<Avatar alt="" color="blue">LT</Avatar>} title="Linh commented" time="2 hours ago">
    <Card className="p-md text-sm">Can we keep the old name for one release?</Card>
  </TimelineItem>
  <TimelineItem avatar={<Avatar alt="" color="green">AP</Avatar>} title="An opened the pull request" time="Yesterday" />
</Timeline>

Failed step

danger marks a failed event; put the retry in the content.

  1. Build1m 12s
    done
  2. Deploy8s
    failed

    The health check timed out.

import { IconCheck, IconX } from "@tabler/icons-react"
import { Button } from "@/components/ui/button"
import { Timeline, TimelineItem } from "@/components/ui/timeline"

<Timeline>
  <TimelineItem status="success" icon={<IconCheck />} title="Build" time="1m 12s" />
  <TimelineItem status="danger" icon={<IconX />} title="Deploy" time="8s" description="The health check timed out.">
    <Button size="sm" variant="outline">Retry</Button>
  </TimelineItem>
</Timeline>

Horizontal

orientation="horizontal" lays events out in equal columns that scroll sideways when narrow.

  1. PlacedOct 20
    done
  2. ShippedOct 21
    done
  3. Out for deliveryOct 24
    in progress
  4. Delivered
import { Timeline, TimelineItem } from "@/components/ui/timeline"

<Timeline orientation="horizontal">
  <TimelineItem status="success" title="Placed" time="Oct 20" />
  <TimelineItem status="success" title="Shipped" time="Oct 21" />
  <TimelineItem status="info" title="Out for delivery" time="Oct 24" current />
  <TimelineItem title="Delivered" />
</Timeline>

Do and don't

Do

  • Put events in the order they happened, oldest first, unless the newest matters most, as in an activity feed.
  • Use status for the outcome of an event, and say it in the title too.
  • Use one kind of marker per Timeline where you can; mix icons and avatars only when who acted matters.

Don't

  • Do not use Timeline for the steps of a flow the user moves through; use Stepper.
  • Do not rely on the marker color alone; statusLabels and the title carry the meaning.
  • Do not put long forms inside an event; link to a page instead.

Props

NameTypeValuesDefaultDescription
orientationenumvertical | horizontalverticalvertical stacks events down the page; horizontal lays them out in equal columns that scroll sideways when narrow.
sizeenumsm | md | lgmdMarker box, text and spacing: 24, 32 or 40px markers.
statusLabels{ success?: string; warning?: string; danger?: string; info?: string }--Words read after a title for each status. Defaults: done, needs attention, failed, in progress. Vietnamese: xong, cần chú ý, thất bại, đang chạy.
statusenumdefault | success | warning | danger | infodefaultOn TimelineItem. Colors the marker from the status tokens.
iconnode--On TimelineItem. An icon in a soft status circle, in place of the dot.
avatarnode--On TimelineItem. An Avatar in place of the dot, such as the person who acted. Give it the Timeline's size.
titlenode--On TimelineItem. What happened.
timenode--On TimelineItem. When it happened, as shown, such as 10:42 or 2 hours ago.
dateTimestring--On TimelineItem. A machine-readable date for time, such as 2026-10-24T10:42.
descriptionnode--On TimelineItem. A line or two of detail under the title.
currentboolean-falseOn TimelineItem. Marks the current event with aria-current="step".
scrollLabelstring-TimelineNames the scroll region of a horizontal timeline, which the keyboard can focus to scroll. Default "Timeline".

Anatomy

PartDescription
rootThe ol: events stacked down the page, or in a row that scrolls sideways when narrow.
itemOne event, a li: the rail, then the body.
railThe marker and the line to the next marker. Hidden from screen readers.
markerA box the size of the marker (24, 32 or 40px) that holds a dot, an icon in a soft status circle, or an avatar, so titles line up whatever the marker. Dots use the solid status color (color-gray, color-success, color-warning, color-danger, color-info); icons use the soft status fill and text (color-background-* with color-text-*).
connectorThe 1px line (border-strong) from one marker to the next, with a gap at both ends. The last event has none.
bodyThe title row, the description and the content.
titleWhat happened, in medium weight primary text.
timeWhen it happened, in secondary text with tabular numbers. Vertical: on the title's row, never wrapping under it. Horizontal: always under the title.
descriptionA line or two of detail in secondary text.
contentAnything under the description, such as a Card, a CodeBlock or Buttons.

Accessibility

Role: list

KeysAction
TabMoves through any links or buttons inside the events. The list itself takes no focus.
  • The Timeline is an ordered list, so screen readers announce the number of events and the position of each one.
  • Markers and lines are hidden from screen readers. A status other than default adds words after the title, EN `done`, `needs attention`, `failed`, `in progress`; change them with statusLabels.
  • current marks one event with aria-current="step".
  • Give time a dateTime so it renders as a time element with a machine-readable date.

Install

npx werewolf-ui add timeline

Run npx werewolf-ui init once in your app before adding components. Init sets up tokens, their CSS import and agent rules. Add installs this component and its dependencies while preserving your theme. See Installation for requirements and the alternative registry setup.