---
title: Steps
description: A collapsible timeline of a run — reasoning, tool calls, and answered questions as chronological steps.
source: steps.tsx
---

<ComponentPreview name="steps-basic" />

## Usage guidelines

- **Recursive disclosure tree** — every node is a `Steps.Item` with a `Trigger` and a `Panel`, and panels can hold further items, so timelines nest arbitrarily.
- **Status-driven** — each item's `status` (`complete` / `active` / `pending`) flows to its `Icon` and `Label` via context; active items open by default.
- **Nesting** — a nested item surfaces `data-nested` for the indent rail; a static row is just an `Icon` + `Label` in a `<div>`.
- **You compose the rows** — the primitive ships the disclosure + status plumbing; row content (icons, tool-call summaries) is yours to render.
- **Get started** — see [Installation](/docs/installation) to add the package and copy the component.

## Anatomy

A timeline is a top-level item whose panel holds rows; a row is an `Icon` +
`Label`, and a row that expands is itself a nested `Steps.Item`:

```tsx
<Steps>
  <Steps.Item defaultOpen>
    <Steps.Trigger>
      <span>Worked for 3 seconds</span>
    </Steps.Trigger>
    <Steps.Panel>
      {/* a static, complete row */}
      <div>
        <Steps.Icon>{checkIcon}</Steps.Icon>
        <Steps.Label>Read the request</Steps.Label>
      </div>

      {/* a nested, expandable row */}
      <Steps.Item defaultOpen>
        <Steps.Trigger>
          <Steps.Icon>{checkIcon}</Steps.Icon>
          <Steps.Label>Searched the web</Steps.Label>
        </Steps.Trigger>
        <Steps.Panel>Found three relevant sources and skimmed each.</Steps.Panel>
      </Steps.Item>

      {/* an in-progress row — status overrides icon + label styling */}
      <div>
        <Steps.Icon status="active">{spinnerIcon}</Steps.Icon>
        <Steps.Label status="active">Writing the answer</Steps.Label>
      </div>
    </Steps.Panel>
  </Steps.Item>
</Steps>
```

## Status

`status` is an opaque `string` — you own the set (commonly `"complete"`,
`"active"`, `"pending"`, but add `"error"`/`"skipped"`/anything). `Steps.Item`
takes a `status` and publishes it through context; `Steps.Icon` and
`Steps.Label` inherit it, or override with their own `status`. Resolution is
*own prop → inherited → `"complete"`*. Every status-aware part reflects it as
`data-status` for styling.

## Keyboard

Each item is a standard disclosure: `Steps.Trigger` is a real button, so
`Tab` moves between triggers and `Enter`/`Space` toggle the nearest item.
Nested items nest their own triggers — there is no roving focus or composite
widget; the tree is plain sequential tab order.

## Accessibility

Disclosure semantics are inherited from the underlying Collapsible:
`aria-expanded`/`aria-controls` on the trigger, an id-linked, `hidden`-managed
panel. The item whose `status` is `"active"` additionally carries
`aria-current="step"` — the same "active" convention `defaultOpen` already
keys off.

Status itself is invisible to assistive tech by default: `Steps.Icon` is
`aria-hidden` and color never announces. Mount `Steps.Status` inside rows
whose status matters — it renders a visually-hidden span speaking the resolved
status string, and takes `children` for localized copy:

```tsx
<Steps.Trigger>
  <Steps.Icon />
  <Steps.Label>Searching the web</Steps.Label>
  <Steps.Status />
</Steps.Trigger>
```

## API reference

Every part accepts `className`, `style`, and `render` (see
[PrimitiveProps](/docs/headless/types)) and emits a bespoke part attribute (`data-<part>`) unless noted.

### Steps

The timeline root. Renders `data-steps`. No part-specific props.

### Steps.Item

One node of the tree (a disclosure). Renders `data-steps-item`, plus
`aria-current="step"` while `status` is `"active"`.

export const itemProps = [
  { name: "status", type: "string", default: '"complete"', description: "Node status (commonly complete / active / pending); seeds context for Icon/Label and drives data-status." },
  { name: "defaultOpen", type: "boolean", default: "status === active", description: "Uncontrolled initial open state — open by default while active." },
  { name: "open", type: "boolean", description: "Controlled open state." },
  { name: "onOpenChange", type: "(open: boolean) => void", description: "Fires on toggle." },
];

<PropsTable rows={itemProps} />

export const itemAttrs = [
  { attribute: "data-steps-item", description: "The item element." },
  { attribute: "data-status", values: "string", description: "The item's status (commonly complete / active / pending)." },
  { attribute: "data-nested", values: '"true"', description: "Present when the item is inside another item (indent rail)." },
  { attribute: "data-open", description: "Present while open." },
  { attribute: "data-closed", description: "Present while closed." },
];

<AttributesTable rows={itemAttrs} />

### Steps.Trigger

Toggles the nearest item. Renders a `<button data-steps-trigger>`
(`aria-expanded`, `aria-controls`). Carries `data-open`/`data-closed` for the
chevron. The styled layer groups it as `group/steps-trigger` so children read
`group-data-open/steps-trigger:…`.

### Steps.Panel

The nearest item's disclosure area — lays out the timeline column. Renders
`data-steps-panel`.

export const panelProps = [
  { name: "keepMounted", type: "boolean", default: "false", description: "Keep the panel in the DOM (hidden) when closed." },
];

<PropsTable rows={panelProps} />

export const panelAttrs = [
  { attribute: "data-steps-panel", description: "The panel." },
  { attribute: "data-open", description: "Present while open." },
  { attribute: "data-closed", description: "Present while closed." },
  { attribute: "data-starting-style", description: "Present on the first open frame (enter transition)." },
  { attribute: "data-ending-style", description: "Present while the exit animation runs." },
];

<AttributesTable rows={panelAttrs} />

### Steps.Icon

Status indicator. Renders `<span data-steps-icon aria-hidden>`.

export const iconProps = [
  { name: "status", type: "string", description: "Overrides the inherited status for this icon." },
];

<PropsTable rows={iconProps} />

export const iconAttrs = [
  { attribute: "data-steps-icon", description: "The icon element." },
  { attribute: "data-status", values: "string", description: "Resolved status, for styling." },
];

<AttributesTable rows={iconAttrs} />

### Steps.Label

Row text. Renders `<span data-steps-label>`.

export const labelProps = [
  { name: "status", type: "string", description: "Overrides the inherited status for this label." },
];

<PropsTable rows={labelProps} />

export const labelAttrs = [
  { attribute: "data-steps-label", description: "The label element." },
  { attribute: "data-status", values: "string", description: "Resolved status, for styling." },
];

<AttributesTable rows={labelAttrs} />

### Steps.Status

Visually-hidden status announcement. Renders `<span data-steps-status>` with
screen-reader-only styling (overridable via `style`/`className`), containing
the resolved status string unless `children` provide localized copy.

export const statusProps = [
  { name: "status", type: "string", description: "Overrides the inherited status for this announcement." },
  { name: "children", type: "ReactNode", default: "the resolved status string", description: "Localized copy to announce instead of the raw status value." },
];

<PropsTable rows={statusProps} />

export const statusAttrs = [
  { attribute: "data-steps-status", description: "The status element." },
];

<AttributesTable rows={statusAttrs} />