PixelTimeline

Vertical timeline rendered as a semantic ordered list with past/active/upcoming states and surface-aware bullets and connectors.

  • Semantic <ol>/<li> with aria-current="step" on the active entry
  • Configurable bullet size, alignment, and per-item connector variant (solid/dashed/dotted)
  • Surface-aware (pixel/glass/solid) styling via shared surface tokens
  • Connector lines marked aria-hidden so screen readers ignore decoration
Status
stable
Category
data
Since
v1.9.0

API

import { PixelTimeline, PixelTimelineItem } from '@pxlkit/ui-kit';

PixelTimeline

PropTypeDefaultDescription
activenumber—Index of the current entry: the ones before it are past, the ones after it upcoming.
bulletSize'sm' | 'md' | 'lg''md'Bullet size.
align'left' | 'right''left'Side the bullets and the rail sit on.
surface'pixel' | 'linear'—Surface override; defaults to the nearest provider.
children (required)React.ReactNode—The entries (PixelTimelineItem).

Also takes the native attributes and event handlers of <ol> (HTMLAttributes<HTMLOListElement>).

ref points to <ol>.

PixelTimelineItem

PropTypeDefaultDescription
labelstring—Canonical label for the item.
titlestring—Deprecated. Use label instead. Retained as alias for one minor.
bulletReact.ReactNode—Content of the bullet.
timestring—Time or date beside the label.
lineVariant'solid' | 'dashed' | 'dotted''solid'Line style of the rail down to the next entry.
childrenReact.ReactNode—Description below the label.

Also takes the native attributes and event handlers of <li> (HTMLAttributes<HTMLLIElement>).

ref points to <li>.

Accessibility

WCAG target: 2.1 AA

  • semantic ol/li
  • aria-current="step" on active item
  • connectors aria-hidden

Decorative bullets and connector rails are aria-hidden; entry state is exposed via aria-current on the active <li>.

Usage

import { PixelTimeline, PixelTimelineItem } from '@pxlkit/ui-kit';

export function Default() {
  return (
    <PixelTimeline active={1}>
      <PixelTimelineItem title="Order placed" time="09:00">
        Confirmation email sent.
      </PixelTimelineItem>
      <PixelTimelineItem title="Packed" time="11:20">
        At the warehouse.
      </PixelTimelineItem>
      <PixelTimelineItem title="Shipped" time="—">
        Awaiting carrier pickup.
      </PixelTimelineItem>
    </PixelTimeline>
  );
}

Examples

Default

import { PixelTimeline, PixelTimelineItem } from '@pxlkit/ui-kit';

export function Default() {
  return (
    <PixelTimeline active={1}>
      <PixelTimelineItem title="Order placed" time="09:00">
        Confirmation email sent.
      </PixelTimelineItem>
      <PixelTimelineItem title="Packed" time="11:20">
        At the warehouse.
      </PixelTimelineItem>
      <PixelTimelineItem title="Shipped" time="—">
        Awaiting carrier pickup.
      </PixelTimelineItem>
    </PixelTimeline>
  );
}

Dashed connectors

import { PixelTimeline, PixelTimelineItem } from '@pxlkit/ui-kit';

export function Dashed() {
  return (
    <PixelTimeline active={0} bulletSize="lg">
      <PixelTimelineItem title="Draft" lineVariant="dashed">
        Currently editing.
      </PixelTimelineItem>
      <PixelTimelineItem title="Review" lineVariant="dashed">
        Pending approval.
      </PixelTimelineItem>
      <PixelTimelineItem title="Published" lineVariant="dashed" />
    </PixelTimeline>
  );
}

Right aligned

import { PixelTimeline, PixelTimelineItem } from '@pxlkit/ui-kit';

export function RightAligned() {
  return (
    <PixelTimeline active={2} align="right">
      <PixelTimelineItem title="Step 1" time="Mon" />
      <PixelTimelineItem title="Step 2" time="Tue" />
      <PixelTimelineItem title="Step 3" time="Wed" />
    </PixelTimeline>
  );
}