Step Timeline

An expanding step selector with timed progress and accessible manual navigation.

Install with the shadcn CLI

npxnpx shadcn@4.21.5 add @cavemio/step-timeline

First install? Configure @cavemio once

Run npx shadcn@4.21.5 init if shadcn is not set up, then merge this entry into the registries field in your existing components.json. Keep your other settings and registries.

components.json

{
  "registries": {
    "@cavemio": "https://registry.cavemio.dev/r/cavemio-{name}.json"
  }
}

Overview

An expanding step selector with timed progress and accessible manual navigation.

An expanding stage selector with controlled selection and optional autoplay.

import { StepTimeline } from "@/components/step-timeline";

<StepTimeline steps={steps} value={stage} onValueChange={setStage} />

Props

Prop	Type	Description
`steps`	`readonly TimelineStep[]`	Required. Nonempty steps with unique, stable IDs.
`value`	`string`	Optional. Controlled selected step ID.
`defaultValue`	`string`	Optional. Initial selection when uncontrolled.
`onValueChange`	`(value: string) => void`	Optional. Called when the selection changes.
`autoPlay`	`boolean`	Optional. Opt in to timed progression.
`duration`	`number`	Optional. Duration of each timeline step in milliseconds.
`disabled`	`boolean`	Optional. Disable user interaction.
`ariaLabel`	`string`	Optional. Accessible name for the component.
`className`	`string`	Optional. Additional CSS classes for the root element.
`style`	`CSSProperties`	Optional. Inline styles for the root element.