Skip to content
flyingsalmon

Timeline

A timeline places markers in a sequence, joins them with a connector, and puts content beside each one.

  1. Hanoi
    Two nights in the Old Quarter
  2. Ninh Binh
    One night, boats through Tam Coc in the morning
  3. Hoi An
    Three nights on An Bang beach

Installation

npx shadcn@latest add @flyingsalmon/timeline

Usage

import {
  Timeline,
  TimelineContent,
  TimelineDescription,
  TimelineItem,
  TimelineMarker,
  TimelineTitle,
} from '@/components/ui/timeline'

export function TripRoute() {
  return (
    <Timeline>
      <TimelineItem>
        <TimelineMarker />
        <TimelineContent>
          <TimelineTitle>Hanoi</TimelineTitle>
          <TimelineDescription>Two nights</TimelineDescription>
        </TimelineContent>
      </TimelineItem>
      <TimelineItem>
        <TimelineMarker />
        <TimelineContent>
          <TimelineTitle>Hoi An</TimelineTitle>
          <TimelineDescription>Three nights</TimelineDescription>
        </TimelineContent>
      </TimelineItem>
    </Timeline>
  )
}

Examples

Marker sizes

A marker is a slot. Empty, it draws a neutral dot; with an icon, a bordered circle. Small markers suit the legs between places, and both sizes centre on the same line, so the connector stays straight.

  1. Hanoi
    Two nights in the Old Quarter
  2. Train to Ninh Binh
    2h 20m from Hanoi station
  3. Ninh Binh
    One night
  4. Flight to Da Nang
    1h 20m, lands at midday
  5. Hoi An
    Three nights on An Bang beach

Linked title

Put an anchor in the title and it takes the underline, the colour, and the hover. Add the offset focus ring from the interaction lib to the anchor; the timeline itself stays free of that dependency.

  1. Two nights in the Old Quarter
  2. Ninh Binh
    One night

Horizontal

Content sits below the marker and every item takes an equal share of the width, so markers stay evenly spaced however long the content runs.

  1. Hanoi
    2 nights
  2. Ninh Binh
    1 night
  3. Hoi An
    3 nights

Strip

A strip is a horizontal timeline whose items leave out TimelineContent. There is no separate component and no hidden-content mode.

Spacing

The gap between items comes from --timeline-spacing on the root, and the connectors that bridge the gaps follow it. Set it with className.

  1. Hanoi
  2. Ninh Binh
  3. Hoi An

A moving current marker

Press Next day. The current marker travels from day to day.

Guidelines

When to use

  • To show a route or an itinerary: cities, legs between them, days of a trip.
  • When each item has a title and a line of detail that belong beside its marker.

When not to use

  • Use Stepper to show a position in a sequence of known length with no content beside it, because a stepper shows only where the traveller is.
  • Use Table to compare the same fields across items, because columns line up what a rail cannot.

Do and don’t

  • Do
    Let the marker say what kind of stop it is, and give every stop of one kind the same marker: an icon for a leg, a dot for a place.The traveller reads the rhythm of the route from its markers before reading a word.
  • Do
    Mark the current stop with a marker of your own, and let it travel to the next stop when the traveller moves on.The rail gives every stop the same neutral mark, because done, current, and ahead are claims only your app can make. A marker that travels shows the move instead of redrawing the rail.
  • Don’t
    Put an action on each stop. The action the route leads to, such as approving it, sits below the whole timeline.A route is read top to bottom and then acted on once. Buttons on every stop turn it into a list of chores.
  • Don’t
    Stretch a link over a whole item.An item is never a hit target; only its title links. One linked title costs the keyboard user one stop, however many cities the rail holds.

Accessibility

KeyDescription
TabReaches one stop per linked title, in document order. Nothing else in the timeline is focusable.
EnterFollows the focused link in a title.

The root is an ol and every item an li, so a screen reader announces the order and the count with no extra ARIA. The connector is hidden from assistive technology. Icons you put in a marker should be decorative too, because the title beside the marker already names the stop.

API

Timeline

Also takes every <ol> attribute. Every part carries a data-slot, and the root exposes data-orientation for styling around it.

PropTypeDefaultDescription
orientationTimelineOrientationTimelineOrientation.VerticalVertical puts content beside the marker. Horizontal puts it below and shares the width equally.

TimelineMarker

Also takes every <span> attribute. It draws the connector to the next item; the last item and an item with no marker have none. It has no status or active state: paint a current marker through its children.

PropTypeDefaultDescription
sizeTimelineMarkerSizeTimelineMarkerSize.DefaultDefault or Small. Both centre on the same line, so a vertical rail can mix them. A horizontal timeline uses one size throughout: each connector spans from its own marker’s edge, so mixed sizes overshoot at one end.
childrenReactNode–An icon or a custom mark. Empty, the marker draws a neutral dot.

TimelineItem takes the <li> props. TimelineContent, TimelineTitle, and TimelineDescription take the <div> props; title and description mirror the card’s typography.

  • Stepper

    Shows a position in a sequence with no content beside it.
  • Table

    Compares the same fields across many items.
  • Text link

    The link inside a sentence, whose underline weights a linked title shares.
  • Motion

    The bounce spring a moving marker uses.