Skip to content
Fuji UI
Component

Timeline

Connects dated entries with a line and a status-colored dot. items takes title, an optional description and timestamp, and an optional variant (StatusTone) that colors the dot. layout controls left (default), right, or alternating placement, and groups lays out a history instead: a year on a centered axis with media on one side and dated entries on the other.

Left-aligned (default)

layout='left': the line sits on the left, content to its right.

  1. Success: Order confirmed

    Mon 9:02 AM

    Payment captured and confirmation email sent.

  2. Success: Packed

    Mon 3:40 PM

    Items picked and boxed at the Osaka warehouse.

  3. Info: Out for delivery

    Tue 8:00 AM

    Handed to the regional courier for last-mile delivery.

  4. Delivered

    Pending

    Awaiting courier confirmation.

  • Items without a variant (like "Delivered" above) render as the neutral, in-progress style - that's how a pending/in-progress step is expressed

Right-aligned

layout='right': the line moves to the right, content sits to its left - useful when the timeline anchors a right-hand rail.

  1. Success: Order confirmed

    Mon 9:02 AM

    Payment captured and confirmation email sent.

  2. Success: Packed

    Mon 3:40 PM

    Items picked and boxed at the Osaka warehouse.

  3. Info: Out for delivery

    Tue 8:00 AM

    Handed to the regional courier for last-mile delivery.

  4. Delivered

    Pending

    Awaiting courier confirmation.

Alternating

layout='alternating': a centered line with content flipping sides per entry - reads well for a wide, narrative history. Collapses to left below the sm breakpoint, since alternating needs width a phone screen doesn't have.

  1. Success: Company founded

    2019

    Success: Company founded

    2019

  2. Success: Seed round closed

    2020

    Success: Seed round closed

    2020

  3. Success: Series A

    2022

    Success: Series A

    2022

  4. Info: Opened Tokyo office

    2024

    Info: Opened Tokyo office

    2024

  5. Series B in progress

    2026

    Series B in progress

    2026
  • Resize the browser below the sm breakpoint to see this example collapse to the left layout automatically - no separate mobile prop needed

Activity feed with status dots

variant (StatusTone: default | success | warning | danger | info) colors each entry's dot - the same semantic vocabulary as Alert and Toast, not the decorative ComponentTone used by Button or Badge.

  1. Kenji commented on PR #482

    2m ago

  2. Success: Priya approved PR #482

    10m ago

  3. Error: Build failed on main

    1h ago

    3 tests failed in checkout.spec.ts

  4. Warning: Deploy queued, waiting on approval

    1h ago

History with groups

groups replaces items and layout. Each group's label sits on a centered axis with a dot beneath it, its media on the left and its dated entries on the right. Below the sm breakpoint it collapses to a single column.

  1. 2026

    Mountain lake at sunrise
    Team offsite
    1. Mar

      Opened the Tokyo office

    2. Jan

      Success: Series B closed

  2. 2025

    1. Oct

      Shipped the public API

    2. Jun

      Crossed 10,000 teams

    3. Feb

      Hired the first designer

  3. 2024

    Forest path
    Where it started
    1. Nov

      Success: Seed round closed

    2. Apr

      Company founded

  • A group without media keeps its entries in the right-hand column, so the axis stays centered
  • Timestamps sit in a narrow column before each title - keep them short, such as a month

When to use

  • A chronological sequence read top to bottom - an order's progress, an activity feed, a release history.
  • Entries that each carry a status, where the dot color plus its announced label communicate state.
  • A wide, narrative history (use layout='alternating' or groups) where dates anchor a centered axis.

When not to use

  • A guided, numbered task flow with a current step and progress - use Stepper.
  • A plain unordered set of items with no time or sequence - use List.

Keyboard

KeyAction
TabTimeline itself is static; only interactive content you place inside an entry (a link or button) enters the tab order.

Accessibility notes

  • Renders as an ordered list, so a screen reader conveys count and order.
  • A variant is announced as a visually-hidden prefix ("Error: Build failed on main"), so status is never color-only; statusLabel translates or suppresses it per item.
  • Today/pending entries carry the neutral style rather than a status color, and read as in-progress.

Common mistakes

  • Relying on the dot color alone in custom entry content - keep the status in the text as Fuji UI's default does.
  • Using Timeline for an interactive step wizard - that's Stepper's job.

Known limitations

  • alternating and groups are visual layouts; below the sm breakpoint alternating collapses to a single left column.

Related components

StepperListChat Bubble
CriterionStatusNote
Keyboard supportNot applicableA static, non-interactive ordered list - nothing to operate by keyboard.
Focus managementNot applicableNot an overlay - no focus trap or portal involved.
Screen reader labelsSupportedRenders a real <ol>, so entry order and count are announced natively; status is carried by text (title/description), never color alone.
Reduced motionSupportedNo motion beyond the shared Fuji UI transition tokens, which zero under prefers-reduced-motion.
Reduced transparencyNot applicableUses opaque surfaces in every theme.
Mobile touch behaviorSupportedAlternating layout collapses to left below the sm breakpoint so entries never compress into an unreadable center column.

API reference

groupsNone
TimelineGroup[]

History timeline: each group's `label` centred on a vertical axis above a dot, `media` left, `items` right (timestamp, then title). Replaces `items`/`layout`; single column below `sm`.

items[]
TimelineItem[]

The entries, newest first by convention. Optional when `groups` is given instead.

layout"left"
"left" | "right" | "alternating"

"left" (default): line left, content right. "right": the mirror. "alternating": centered line, content flipping sides per item; collapses to "left" below `sm` (phones lack the width).

Also accepts everything from React.HTMLAttributes<HTMLOListElement>.

Coding agents read this reference, with its examples, from the version your project has installed, through the Fuji UI MCP server. Set up your agent