# StepIndicator

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

Interactive docs and examples: [StepIndicator in Storybook](https://storybook-tangible-ui.pages.dev/?path=/docs/primitives-stepindicator--docs).

## StepIndicator props

| Prop | Type | Default | Description |
| - | - | - | - |
| `className?` | `string` | | Additional CSS class names. |
| `icon?` | `IconName` | | Custom icon to display instead of the default status icons. Shows for `not-started` and `in-progress` states; `complete` always shows checkmark (completion is universal); `locked` always shows lock (access restriction is universal) Use for content-type indicators like quizzes, readings, videos. |
| `label?` | `string` | | Accessible label for the indicator. Used as aria-label when the indicator conveys unique information. If omitted, defaults to "Step status: {status}". |
| `labels?` | `StepIndicatorLabels` | | Override default English strings for i18n. Covers status display names and the aria-label template. |
| `showValue?` | `boolean` | `false` | Show percentage text in center (only visible for in-progress status). |
| `size?` | `"lg" \| "md" \| "sm" \| "xs"` | `'sm'` | Size of the indicator. `'xs'`: 16px circle; `'sm'`: 24px circle (default); `'md'`: 32px circle; `'lg'`: 40px circle |
| `status?` | `"complete" \| "in-progress" \| "locked" \| "not-started"` | | Override the inferred status. By default, status is derived from `value`. Set this explicitly for: `'locked'` — Shows lock icon regardless of value; Force a specific state when value doesn't reflect actual status |
| `value?` | `number` | `0` | Progress value (0-100). Status is inferred from value by default: `value = 0` → not-started; `0 < value < 100` → in-progress; `value >= 100` → complete Use the `status` prop to override inference (e.g., for locked steps). |

## Examples

- [Accessibility (Labels)](https://storybook-tangible-ui.pages.dev/?path=/story/primitives-stepindicator--accessibility): All announced strings route through `labels`. When `showValue` displays a percentage, the accessible label carries it too (`labels.statusWithValue`) — the label must say what the eye can see. The status display names (`notStarted`/`inProgress`/`complete`/`locked`) and both label templates are all translatable.

Other stories: Playground, Status Inference, All States, Sizes, With Value Display, Custom Icon (Quiz), Course Syllabus ([interactive page](https://storybook-tangible-ui.pages.dev/?path=/docs/primitives-stepindicator--docs)).

## Component API tokens

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

- `--tui-progress-track`
- `--tui-progress-fill`

---

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