Guides users through the ordered stages of a task.
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.
Basic usage
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
1
A rather long first title
with a subtitle
And a long description that will be truncated.
2
Also truncated when needed.
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.
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.
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>
);
}