StepList

import { StepList } from '@tangible/ui';

Interactive docs and examples: StepList in Storybook.

StepList props

Prop	Type	Default	Description
`children`	`ReactNode`		StepList.Item children.
`aria-label?`	`string`		Accessible label for the navigation landmark. Use either `aria-label` or `aria-labelledby`, not both.
`aria-labelledby?`	`string`		ID of a visible heading that labels the navigation. Use either `aria-label` or `aria-labelledby`, not both.
`ariaCurrent?`	`"page" \| "step"`	`'step'`	What `aria-current` value to use for the current item. `'step'`: For step-by-step progressions (default); `'page'`: For page navigation
`className?`	`string`		Additional CSS class names.
`current?`	`string`		Value of the currently active step. The matching StepList.Item will receive `aria-current` and current styling.
`labels?`	`StepListLabels`		Override the strings each item announces after its label ("Complete", "needs attention", "current step").
`onSelect?`	`(value: string) => void`		Callback when a step is selected (clicked or activated). Without `onSelect`, an item with no `href` renders as plain content, not a button: a status-only list has nothing to activate. If no item has an `href` either, the root is a labelled list instead of a `nav` landmark.

StepList.Item

Prop	Type	Default	Description
`children`	`ReactNode`		Step label/content.
`value`	`string`		Unique identifier for this step. Used to determine if this item is current and passed to `onSelect` callback.
`attention?`	`boolean`	`false`	Flag the step as needing attention (stale inputs, needs review). Shows a warning dot on the indicator and adds "needs attention" to its name. Independent of `status`.
`className?`	`string`		Additional CSS class names.
`disabled?`	`boolean`	`false`	Prevent interaction with this step. Buttons: uses native `disabled` attribute; Anchors: uses `aria-disabled="true"` + `tabIndex={-1}` + prevents click; Plain rows (no `href`, no `onSelect`): visual only, since there's nothing to disable. Use `status="locked"` to say a step can't be reached.
`href?`	`string`		URL to navigate to. When provided, renders as an anchor element.
`icon?`	`IconSource`		Custom icon to display in the indicator. Only shown for `not-started` status; `complete` always shows checkmark, `locked` always shows lock; `in-progress` shows progress ring (icon ignored)
`progress?`	`number`		Progress value (0-100), only used when `status='in-progress'`.
`status?`	`"complete" \| "in-progress" \| "locked" \| "not-started"`	`'not-started'`	Step status — determines the indicator appearance. `'not-started'`: Empty ring; `'in-progress'`: Ring with progress fill; `'complete'`: Filled circle with checkmark; `'locked'`: Ring with lock icon

Other exports

defaultStepListLabels: Required<StepListLabels>

Examples

Status Only: No onSelect and no href: the items have nothing to activate, so they render as plain rows and the root is a labelled list, not a nav. aria-current still marks the current step.

attention adds a warning dot and "needs attention" to the step's status, independent of status (a complete step whose inputs changed).

Other stories: Basic, With Statuses, Current Step Highlight, With Links, Long Labels + Wrapping, Keyboard Navigation, Inside Narrow Container (interactive page).

Component API tokens

Read via fallback, never declared. Set one on an ancestor to restyle every instance under it.

--tui-steplist-gap
--tui-steplist-padding
--tui-steplist-radius
--tui-steplist-current-bg
--tui-steplist-current-border
--tui-steplist-hover-bg