> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.

# Steps

Navigation`@rockshin/tao-ui`

[Examples](#examples)[API](#api)

Guides users through the ordered stages of a task.

## When to use

Use Steps when the work has a sequence — a checkout flow, an onboarding wizard, a deployment pipeline. Steps also doubles as a progress indicator for a process the user is watching rather than driving.

**Recommended**

- Keep titles to one or two words; move detail into `content`.
- Drive the whole bar from `current` and let the status be derived from position.
- Provide `onChange` when revisiting an already completed step is meaningful.
- Switch to `orientation="vertical"` for long flows or narrow layouts.

**Avoid**

- Do not use Steps for peer views at the same level; use Tabs.
- Do not use Steps for a single indeterminate operation; use Spinner.
- Do not set `status` per item unless a step genuinely failed or was skipped.

## Examples


### Basic usage
```tsx preview
import { Steps } from '@rockshin/tao-ui';

function StepsExample() {
  return (
    <Steps
      current={1}
      items={[
        { title: 'Finished', content: 'This step is done.' },
        { title: 'In Progress', content: 'Working on it now.' },
        { title: 'Waiting', content: 'Not started yet.' },
      ]}
    />
  );
}

export default StepsExample;
```

### Vertical and clickable
`onChange` receives the absolute step index. Clicking the current step is a no-op, and `disabled` items never become interactive.
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';
import { useState } from 'react';

const items = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
  { title: 'Locked', content: 'Unavailable.', disabled: true },
];

function ClickableSteps() {
  const [current, setCurrent] = useState(0);

  return (
    <Stack gap="lg">
      <Steps items={items} current={current} onChange={setCurrent} />
      <Steps
        items={items}
        current={current}
        onChange={setCurrent}
        orientation="vertical"
        style={{ maxWidth: 320 }}
      />
    </Stack>
  );
}

export default ClickableSteps;
```

### Status, variants, and sizes
`status` sets the state of the current step; every other step derives its own state from position. `variant` picks a solid or outlined icon treatment and `size` switches density.
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';

const items = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
];

function StepsStatus() {
  return (
    <Stack gap="lg">
      <Steps items={items} current={1} status="error" />
      <Steps items={items} current={1} variant="outlined" />
      <Steps items={items} current={1} size="small" variant="outlined" />
    </Stack>
  );
}

export default StepsStatus;
```

### Types
`type` changes the whole shape of the bar: `dot` replaces numbered icons with small dots, `navigation` turns each step into a clickable tab with an underline, and `panel` renders steps as contiguous notched panels.
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';
import { useState } from 'react';

const items = [
  { title: 'One', content: 'First step' },
  { title: 'Two', content: 'Second step' },
  { title: 'Three', content: 'Third step' },
];

function StepsTypes() {
  const [current, setCurrent] = useState(1);

  return (
    <Stack gap="lg">
      <Steps items={items} current={current} type="dot" />
      <Steps
        items={items}
        current={current}
        type="navigation"
        onChange={setCurrent}
      />
      <Steps
        items={items}
        current={current}
        type="panel"
        onChange={setCurrent}
      />
      <Steps
        items={items}
        current={current}
        type="panel"
        variant="outlined"
        onChange={setCurrent}
      />
    </Stack>
  );
}

export default StepsTypes;
```

### Inline
`type="inline"` renders a compact dot strip whose descriptions live in tooltips. `offset` shifts the strip along its axis and `titlePlacement` moves the label under the dot.
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';
import { useState } from 'react';

const items = [
  { title: 'One', content: 'First step' },
  { title: 'Two', content: 'Second step' },
  { title: 'Three', content: 'Third step' },
];

function InlineSteps() {
  const [current, setCurrent] = useState(1);

  return (
    <Stack gap="lg">
      <Steps
        items={items}
        current={current}
        type="inline"
        onChange={setCurrent}
      />
      <Steps
        items={items}
        current={current}
        type="inline"
        titlePlacement="vertical"
        offset={1}
        onChange={setCurrent}
      />
    </Stack>
  );
}

export default InlineSteps;
```

### Progress and max count
`percent` draws a progress ring around the current icon. `maxCount` collapses long flows, folding the hidden range into a disabled ellipsis step while `onChange` keeps reporting the original indexes.
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';

const items = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
];

function StepsProgress() {
  return (
    <Stack gap="lg">
      <Steps items={items} current={1} percent={60} />
      <Steps
        current={3}
        maxCount={5}
        items={Array.from({ length: 10 }, (_, index) => ({
          title: `Step ${index + 1}`,
        }))}
      />
    </Stack>
  );
}

export default StepsProgress;
```

### Custom icons
`items[].icon` replaces a single step's glyph. `iconRender` replaces every glyph and receives the step index, the active flag, and an `Icon` component that renders the semantic icon container.
```tsx preview
import { Steps } from '@rockshin/tao-ui';

const items = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
];

function CustomIconSteps() {
  return (
    <Steps
      items={items}
      current={1}
      iconRender={(_node, { index, active }) => (
        <span
          style={{
            width: 32,
            height: 32,
            borderRadius: 8,
            display: 'grid',
            placeItems: 'center',
            fontSize: 12,
            border: `1px solid ${active ? 'currentColor' : 'transparent'}`,
          }}
        >
          {index + 1}
        </span>
      )}
    />
  );
}

export default CustomIconSteps;
```

### Semantic DOM styling
Every part of a step is addressable through `classNames` and `styles`, and each item can override its own parts.
Use `finishIconBackground` and `finishIconColor` to set the built-in finished circle background and check color independently for default, navigation, and panel steps. Dot steps and custom icons are unaffected.
```tsx preview
import { Steps } from '@rockshin/tao-ui';

function StyledSteps() {
  return (
    <Steps
      current={1}
      finishIconBackground="#e5f4e8"
      finishIconColor="#16a34a"
      items={[
        { title: 'Finished', content: 'This step is done.' },
        { title: 'In Progress', content: 'Working on it now.' },
        { title: 'Waiting', content: 'Not started yet.' },
      ]}
      styles={{ itemTitle: { letterSpacing: '0.02em' } }}
      classNames={{ itemContent: 'demo-step-content' }}
    />
  );
}

export default StyledSteps;
```

### Clickable steps
Maintain `current` with `onChange` and update the displayed content after a step changes.
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';

import { useState } from 'react';

const basicItems = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
];

export default function StepsClickable() {
  function Demo() {
    const [current, setCurrent] = useState(0);
    return (
      <Stack gap="md">
        <Steps items={basicItems} current={current} onChange={setCurrent} />
        <p style={{ color: 'var(--tao-color-text-secondary)', fontSize: 13 }}>
          current: {current}
        </p>
      </Stack>
    );
  }
  return <Demo />;
}
```

### Current step error
`status="error"` marks the current step as failed; explain the cause in adjacent content.
```tsx preview
import { Steps } from '@rockshin/tao-ui';

const basicItems = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
];

export default function StepsErrorStatus() {
  return <Steps items={basicItems} current={1} status="error" />;
}
```

### Per-step status
Set status per item for workflows that combine completed, failed, and waiting steps.
```tsx preview
import { Steps } from '@rockshin/tao-ui';

export default function StepsPerStepStatus() {
  return (
    <Steps
      current={2}
      items={[
        { title: 'Done', content: 'Finished.' },
        { title: 'Failed', content: 'Something broke.', status: 'error' },
        { title: 'Running', content: 'In progress.' },
        { title: 'Queued', content: 'Not started.' },
      ]}
    />
  );
}
```

### Title placement
Choose where titles sit relative to step indicators to suit the available space.
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';

const basicItems = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
];

export default function StepsTitlePlacement() {
  return (
    <Stack gap="lg">
      <Steps items={basicItems} current={1} titlePlacement="horizontal" />
      <Steps items={basicItems} current={1} titlePlacement="vertical" />
    </Stack>
  );
}
```

### Progress within a step
Use `percent` for progress within the current step and change it in this example.
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';

import { useState } from 'react';

const basicItems = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
];

export default function StepsWithProgress() {
  function Demo() {
    const [percent, setPercent] = useState(40);
    return (
      <Stack gap="md">
        <Steps
          items={basicItems}
          current={1}
          percent={percent}
          onChange={() => setPercent((p) => (p >= 100 ? 10 : p + 30))}
        />
        <p style={{ color: 'var(--tao-color-text-secondary)', fontSize: 13 }}>
          percent: {percent}
        </p>
      </Stack>
    );
  }
  return <Demo />;
}
```

### Dot steps
`type="dot"` uses compact nodes for tracking status.
```tsx preview
import { Steps } from '@rockshin/tao-ui';

const basicItems = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
];

export default function StepsDotStyle() {
  return <Steps items={basicItems} current={1} type="dot" />;
}
```

### Custom step dots
Customize step dots with a render callback while retaining titles and status.
```tsx preview
import { Steps } from '@rockshin/tao-ui';

const basicItems = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
];

export default function StepsDotWithCustomDot() {
  return (
    <Steps
      items={basicItems}
      current={1}
      type="dot"
      iconRender={() => (
        <span
          style={{
            width: 10,
            height: 10,
            borderRadius: '50%',
            background: 'currentColor',
          }}
        />
      )}
    />
  );
}
```

### Navigation steps
Navigation steps support switching between stages of a workflow.
```tsx preview
import { Steps } from '@rockshin/tao-ui';

import { useState } from 'react';

export default function StepsNavigation() {
  function Demo() {
    const [current, setCurrent] = useState(0);
    return (
      <Steps
        type="navigation"
        current={current}
        onChange={setCurrent}
        items={[
          { title: 'Step 1', content: 'First' },
          { title: 'Step 2', content: 'Second' },
          { title: 'Step 3', content: 'Third' },
        ]}
      />
    );
  }
  return <Demo />;
}
```

### Panel steps
Panel steps provide a larger area for titles, descriptions, and interaction.
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';

import { useState } from 'react';

export default function StepsPanel() {
  function Demo() {
    const [current, setCurrent] = useState(1);
    return (
      <Stack gap="lg">
        <Steps
          type="panel"
          current={current}
          onChange={setCurrent}
          items={[
            { title: 'One' },
            { title: 'Two' },
            { title: 'Three' },
            { title: 'Four' },
          ]}
        />
        <Steps
          type="panel"
          variant="outlined"
          current={current}
          onChange={setCurrent}
          items={[
            { title: 'One' },
            { title: 'Two' },
            { title: 'Three' },
            { title: 'Four' },
          ]}
        />
      </Stack>
    );
  }
  return <Demo />;
}
```

### Limit visible steps
Use `maxCount` for a long workflow and observe how the visible range follows the current step.
```tsx preview
import { Steps } from '@rockshin/tao-ui';

export default function StepsMaxCount() {
  return (
    <Steps
      current={3}
      maxCount={5}
      items={Array.from({ length: 10 }, (_, index) => ({
        title: `Step ${index + 1}`,
      }))}
    />
  );
}
```

### Disabled steps
Disable unavailable steps without disabling navigation to the others.
```tsx preview
import { Steps } from '@rockshin/tao-ui';

export default function StepsDisabledStep() {
  return (
    <Steps
      current={1}
      onChange={() => {}}
      items={[
        { title: 'First' },
        { title: 'Second' },
        { title: 'Locked', disabled: true },
      ]}
    />
  );
}
```

### Long title ellipsis
Truncate long titles in constrained space and put detail in step content.
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';

const basicItems = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
];

export default function StepsEllipsis() {
  return (
    <Stack gap="lg">
      <div style={{ maxWidth: 520 }}>
        <Steps items={basicItems} current={1} ellipsis />
      </div>
      <div style={{ maxWidth: 520 }}>
        <Steps
          items={[
            {
              title: 'A rather long first title',
              subTitle: 'with a subtitle',
              content: 'And a long description that will be truncated.',
            },
            { title: 'Second', content: 'Also truncated when needed.' },
          ]}
          current={0}
          ellipsis
        />
      </div>
    </Stack>
  );
}
```

### Initial step number
Use `initial` to offset displayed numbers while keeping the component index contract for `current`.
```tsx preview
import { Steps } from '@rockshin/tao-ui';

const basicItems = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
];

export default function StepsInitial() {
  return <Steps items={basicItems} initial={2} current={3} />;
}
```

### Inherit provider settings
Inherit size and appearance settings and override them on an individual Steps instance.
```tsx preview
import { Steps, TaoProvider } from '@rockshin/tao-ui';

const basicItems = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
];

export default function StepsProviderInherit() {
  return (
    <TaoProvider size="small">
      <Steps items={basicItems} current={1} variant="outlined" />
    </TaoProvider>
  );
}
```

## API


### [#](#steps)Steps



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| items | Step data. | `StepItem[] | undefined` | `-` |
| current | Current step, counted from 0. Overridden per step by `items.status`. | `number | undefined` | `-` |
| initial | Numbering offset — the first step is numbered `initial + 1`. | `number | undefined` | `-` |
| status | Status of the `current` step; the others derive theirs from position. | `StepsStatus | undefined` | `process` |
| orientation | Layout axis. | `StepsOrientation | undefined` | `-` |
| titlePlacement | Where the title sits relative to the icon. | `StepsTitlePlacement | undefined` | `-` |
| responsive | Collapse to `vertical` below 576px. | `boolean | undefined` | `true` |
| size | Visual density. | `StepsSize | undefined` | `-` |
| variant | Style variant. | `StepsVariant | undefined` | `filled` |
| type | Steps flavour. | `StepsType | undefined` | `-` |
| percent | Progress ring on the `process` icon; ignored by `type="inline"`. | `number | undefined` | `-` |
| maxCount | Collapse to at most N steps (`>= 3`); hidden ranges become an ellipsis step. | `number | undefined` | `-` |
| offset | Leading flex offset for `type="inline"`. | `number | undefined` | `-` |
| ellipsis | Truncate overflowing titles, subtitles, and content. | `boolean | undefined` | `-` |
| iconRender | Replace the icon node of every step. | `StepsIconRender | undefined` | `-` |
| finishIconBackground | Background of the built-in finished-step circle. | `BackgroundColor | undefined` | `-` |
| finishIconColor | Color of the built-in finished-step check mark. | `Color | undefined` | `-` |
| onChange | Fires with the absolute step index when a non-current step is activated. | `((current: number) => void) | undefined` | `-` |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |

