# StepList

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

Interactive docs and examples: [StepList in Storybook](https://storybook-tangible-ui.pages.dev/?path=/docs/components-steplist--docs).

## 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. |
| `onSelect?` | `(value: string) => void` | | Callback when a step is selected (clicked or activated). |

### 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. |
| `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 |
| `href?` | `string` | | URL to navigate to. When provided, renders as an anchor element. |
| `icon?` | `IconName` | | 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 |

## Examples

Stories: Basic, With Statuses, Current Step Highlight, With Links, Long Labels + Wrapping, Keyboard Navigation, Inside Narrow Container ([interactive page](https://storybook-tangible-ui.pages.dev/?path=/docs/components-steplist--docs)).

## 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`

---

Interactive version: https://storybook-tangible-ui.pages.dev/?path=/docs/components-steplist--docs