Timeline

Lists ordered steps along a sequence of time. Use it where the order is itself the information: an order's fulfilment status, a deployment history.

import { Timeline, TimelineItem } from 'neba';

<Timeline active={2}>
  <TimelineItem title="Ordered" meta="12 Jul">
    Payment taken.
  </TimelineItem>
  <TimelineItem title="In transit" meta="14 Jul" />
  <TimelineItem title="Delivered" />
</Timeline>;

This is not TimelineChart. That one draws spans against a calendar (a Gantt) for how long each piece of work took. This one is a list of steps, and the gaps between them are not to scale.

Props

Timeline

Prop	Type	Default	Description
active	number	—	The index of the item being worked on now: everything before it is complete, everything after it is still to come. An index rather than a value, because a timeline has no selection. Omit it and every item is upcoming; pass the item count to mark the whole sequence done
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Height and type scale
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	Semantic colour role. Arbitrary colour values are not accepted
densityshared	'default' | 'compact'	'default'	The space between items only. Never the type scale, never the bullet
orientationshared	'horizontal' | 'vertical'	'vertical'	Which way the sequence runs. `vertical` is the default and takes any number of steps with anything to say about each; `horizontal` is the stepper across the top of a checkout, and is only honest while every label is short
render	useRender.RenderProp	—	Renders something other than a div (render={<ul />}). Base UI's own escape hatch
children	ReactNode	—	The TimelineItems. They are numbered here, so inserting one in the middle does not mean renumbering the ones after it

active is an index, not a value. Items before it are complete, that item is current, and the rest are upcoming. Omit it and every item is upcoming; pass a number past the item count and all of them are complete.

TimelineItem

Prop	Type	Default	Description
title	ReactNode	—	The heading of this step
meta	ReactNode	—	When it happened: a date, a duration, a name
bullet	ReactNode	—	What goes inside the bullet: a number, an icon, an avatar. Omit it and the bullet is a plain disc
status	'complete' | 'current' | 'upcoming'	—	Overrides what the timeline's `active` computed for this item: a step that failed and stopped the sequence, a step that was skipped
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	—	Overrides the timeline's colour family for this item alone
connector	'solid' | 'dashed' | 'dotted' | 'none'	'solid'	How the line to the next item is drawn. The line belongs to the step it leaves, so it is coloured by whether that step has been reached
children	ReactNode	—	The body of the step

Examples

bullet

bullet takes any node. Numbers suit a procedure a user is walked through; icons suit events that already happened. Omit it and a disc is drawn.

The three states each use a different shape (a filled disc (complete), a filled disc with a halo (current), an empty ring (upcoming)), so the state carries even for a reader who cannot tell the colours apart.

import { Timeline, TimelineItem } from 'neba';

function CheckIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="none">
      <path
        d="m3.5 8.5 3 3 6-6"
        stroke="currentColor"
        strokeWidth="2"
        strokeLinecap="round"
        strokeLinejoin="round"
      />
    </svg>
  );
}

export default function TimelineBullets() {
  return (
    <div className="flex w-full max-w-md flex-col gap-8">
      {/* Numbers, for a sequence somebody is being walked through. */}
      <Timeline active={1} size="lg">
        <TimelineItem bullet="1" title="Account">
          Email and a password.
        </TimelineItem>
        <TimelineItem bullet="2" title="Workspace">
          Name it and pick a region.
        </TimelineItem>
        <TimelineItem bullet="3" title="Invite">
          Optional, and skippable.
        </TimelineItem>
      </Timeline>

      {/* Icons, for a sequence that already happened. */}
      <Timeline active={2} color="success" size="lg">
        <TimelineItem bullet={<CheckIcon />} title="Built" meta="1m 12s" />
        <TimelineItem bullet={<CheckIcon />} title="Tested" meta="3m 40s" />
        <TimelineItem title="Deploying" meta="running" />
      </Timeline>
    </div>
  );
}

status and color

active describes a sequence that is going to plan. A state an index cannot express (a step that failed and stopped) is set per item with status and color.

connector is the shape of the line to the next item. The line belongs to the step it leaves rather than the one it arrives at, so it is coloured by that step's state. none removes it, which is how you group items inside one Timeline.

import { Timeline, TimelineItem } from 'neba';

/**
 * `active` describes a sequence that is going to plan. A step that failed and
 * stopped it is not something an index can say, which is what the per-item
 * `status` and `color` overrides are for.
 */
export default function TimelineStatus() {
  return (
    <div className="w-full max-w-md">
      <Timeline active={2}>
        <TimelineItem title="Queued" meta="09:31">
          Picked up by the runner.
        </TimelineItem>
        <TimelineItem title="Built" meta="09:33" connector="dashed">
          Artifacts uploaded.
        </TimelineItem>
        <TimelineItem title="Tests failed" meta="09:36" color="danger" status="current">
          3 of 412 assertions did not pass.
        </TimelineItem>
        <TimelineItem title="Deploy" status="upcoming">
          Blocked until the tests pass.
        </TimelineItem>
      </Timeline>
    </div>
  );
}

orientation

horizontal is the stepper across the top of a checkout. It has no room for many steps or long labels, so keep them short.

import { Timeline, TimelineItem } from 'neba';

export default function TimelineHorizontal() {
  return (
    <div className="w-full max-w-2xl">
      <Timeline orientation="horizontal" active={1} density="compact">
        <TimelineItem bullet="1" title="Cart" meta="3 items" />
        <TimelineItem bullet="2" title="Delivery" meta="Address" />
        <TimelineItem bullet="3" title="Payment" meta="Card" />
        <TimelineItem bullet="4" title="Done" />
      </Timeline>
    </div>
  );
}

Accessibility

• Renders an <ol>, so it is announced as an ordered list.
• The current item carries aria-current="step".

When to use something else

• To show current progress rather than a record of what happened, use ProgressLinear.
• If the order carries no meaning, use List. A Timeline's line asserts that one thing came after another.