> ## Documentation Index
> Fetch the complete documentation index at: https://anvil.servicetitan.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Stepper - Web
> Steppers show a user's progress through multiple steps.
> [!NOTE]
>
> For development, import `Stepper` from
> `@servicetitan/anvil2`. For design, find it in the
> [Anvil2 file](https://www.figma.com/design/xaNQsvRKczoxu7pj0M6QT8/Anvil2-v3?node-id=2622-7218).
## Anatomy
The Stepper consists of four primary elements that work together to show a user's progress through multiple steps.
1. Completed step
2. Current step
3. Not started step
4. Step label
## Options
The Stepper supports horizontal orientation and configurable step count to accommodate various progress tracking scenarios.
#### Horizontal
stepper-horizontal
[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/stepper-horizontal?file=src/App.tsx)
```tsx lines theme={null}
import { Stepper } from "@servicetitan/anvil2";
function App() {
return (
Step Label
Step Label
Step Label
Step Label
);
}
export default App;
```
Steppers are horizontal by default.
#### Step Count
stepper-children
[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/stepper-children?file=src/App.tsx)
```tsx lines theme={null}
import { Stepper, Flex } from "@servicetitan/anvil2";
function App() {
return (
Step Label
Step Label
Step Label
Step Label
Step Label
Step Label
Step Label
Step Label
Step Label
);
}
export default App;
```
Steppers support 2–6 steps.
## Behavior
The Stepper responds to different screen sizes with responsive behaviors while handling label overflow.
### Visual States
#### Default
stepper-nonlinear-false
[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/stepper-nonlinear-false?file=src/App.tsx)
```tsx lines theme={null}
import { Stepper } from "@servicetitan/anvil2";
function App() {
return (
Default
Selected
In Progress
Complete
Focus Visible (false)
);
}
export default App;
```
#### Overflow
Labels wrap when they exceed available space.
stepper-overflow
[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/stepper-overflow?file=src/App.tsx)
```tsx lines theme={null}
import { Stepper, Flex } from "@servicetitan/anvil2";
function App() {
return (
Step Label that is very long and will overflow
Step Label
Step Label
Step Label
Step Label
Step Label
Add vertical example here
);
}
export default App;
```
#### Responsive
stepper-width
[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/stepper-width?file=src/App.tsx)
```tsx lines theme={null}
import { Stepper } from "@servicetitan/anvil2";
function App() {
return (
Step Label
Step Label
Step Label
Step Label
Step Label
);
}
export default App;
```
Smaller screens use the mobile variant.
## Usage Guidelines
Use the Stepper when users need to be guided through a linear series of steps to complete a task.
| Standard | Requirement |
| - | - |
| DoKeep one active step | The active step is always the step the user is specifically on; see [Always have one Step active in incomplete Steppers](#always-have-one-step-active-in-incomplete-steppers). |
| DoNavigate with Buttons | The Stepper alone should never be the only means of navigating between steps — provide forward and back actions elsewhere; see [Always use Buttons to navigate the Stepper](#always-use-buttons-to-navigate-the-stepper). |
| Don'tNavigation | Use a navigation-focused component instead of a Stepper. |
| Don'tNon-linear progression | Steps that can be completed in any order. See [Stepper Base](https://anvil.servicetitan.com/docs/components/stepper/base/web.md) for an alternative. |
| Don'tToo few or too many steps | Steppers support 2–6 steps; avoid having too few or too many. See [Number of steps](#number-of-steps). |
### Alternatives
#### Stepper vs Stepper Base
Stepper is a linear wizard. Completeness is derived from the current step. Use Next and Previous to move through the flow.
Stepper Base is a status tracker. The product sets the current step and each step's outcome. A step can be current and complete at the same time. See [Stepper Base](https://anvil.servicetitan.com/docs/components/stepper/base/web.md).
#### Stepper vs Edit Card
Steppers move through a linear progression of steps. Edit Cards can be used for both linear and unrelated blocks of content.
Steppers are typically scoped to the whole view, e.g., a fullscreen Dialog, while an Edit Card can be scoped within smaller sections of a view, e.g., part of a Drawer screen.
Steppers can only give summaries of the flow indirectly, typically on the final step of a flow, while an Edit Card can show a summary in most of its states.
Steppers and Edit Cards may be used together if a particular flow is complex enough.
#### Stepper vs Tab
Tabs help organize information about a subject on the page, while a Stepper helps complete a flow. They can't substitute for each other, although both could be used on the same page.
### How to Use
#### Always have one Step active in incomplete Steppers
The active step is always the step the user is specifically on. By default this is the first step.
stepper-active-do
[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/stepper-active-do?file=src/App.tsx)
```tsx lines theme={null}
import { Stepper } from "@servicetitan/anvil2";
function App() {
return (
Step 1
Step 2
Step 3
);
}
export default App;
```
> [!TIP]
>
> **Do**
Example on step 2. In this scenario, step 1 will always be completed.
#### Always use Buttons to navigate the Stepper
The Stepper alone should never be the only means of navigating between steps. Actions to go forward and back should be provided somewhere in the experience.
stepper-button-do
[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/stepper-button-do?file=src/App.tsx)
```tsx lines theme={null}
import { Stepper, Flex } from "@servicetitan/anvil2";
function App() {
const stepData = [
{
id: "s1",
controls: "p1",
title: "Step 1",
content: "Step 1",
},
{
id: "s2",
controls: "p2",
title: "Step 2",
content: "Step 2",
},
{
id: "s3",
controls: "p3",
title: "Step 3",
content: "Step 3",
},
{
id: "s4",
controls: "p4",
title: "Step 4",
content: "Step 4",
},
];
return (
{stepData.map((step) => (
{step.title}
))}
{stepData.map((step) => (
{step.content}
))}
);
}
export default App;
```
> [!TIP]
>
> **Do**
#### Linear steps
Steppers should follow a linear sequence, meaning a user must complete the steps in a specific order.
#### Returning to, and editing previous steps
When users return to previous steps in an incomplete flow, the Stepper itself will prevent users from returning back. The component does not alter user responses, the consequences of users editing prior steps is on the implementor. Some options to consider include:
* Clearing all subsequent steps when a user edits a previous step
* Identifying which changes impact downstream inputs, and warning users about the changes. No impact changes do not influence future steps.
#### Number of steps
Steppers support 2–6 steps. If a flow requires more than 6 steps, consider breaking it up into smaller chunks.
stepper-children-dont
[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/stepper-children-dont?file=src/App.tsx)
```tsx lines theme={null}
import { Stepper, Flex } from "@servicetitan/anvil2";
function App() {
return (
One step Stepper
Step 1
Step 2
Step 3
Step 4
Step 5
Step 6
Step 7
);
}
export default App;
```
> [!CAUTION]
>
> **Don't**
Avoid having too few or too many steps.
#### Avoid conditionally generated steps
Within an established Stepper, user decisions within the flow should not change the number of steps, i.e., if a flow starts with 5 steps, it should always end with 5 steps.
## Keyboard Interaction
Users can navigate the Stepper using standard keyboard controls.
| Key | Interaction |
| - | - |
| Tab | Navigates linked steps in normal Tab order |
| Enter | Selects the focused linked step |
## Code
**Implementation**
stepper-playground
[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/stepper-playground?file=src/App.tsx)
```tsx lines expandable theme={null}
import { Stepper, Flex } from "@servicetitan/anvil2";
function App() {
return (
First Step
Second Step
Third Step
);
}
export default App;
```
For flows where you need additional control over step progression, use [`StepperBase`](https://anvil.servicetitan.com/docs/components/stepper/base/web).
## Common Examples
```tsx theme={null}
import { Stepper } from "@servicetitan/anvil2";
function ExampleComponent() {
return (
First Step
Second Step
{/* panel content */}
{/* panel content */}
);
}
```
### Adding stepper content
Content can be added to the `Stepper` by using `Stepper.Panel`. The `id` on a `Stepper.Panel` must match with the `controls` on its associated `Stepper.Step` to ensure proper functionality and display of the content.
Content can be added to the end of the `Stepper` by using `Stepper.FinalPanel`.
stepper-panel
[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/stepper-panel?file=src/App.tsx)
```tsx lines expandable theme={null}
import { Stepper, Flex } from "@servicetitan/anvil2";
function App() {
return (
Step 1
Step 2
Step 3
Step 4
Step 1 Content
Step 2 Content
Step 3 Content
The process is complete.
);
}
export default App;
```
### Preventing step on stepper next button
In some cases, validation or other asynchronous functionality needs to occur before the user progresses to the next step.
To prevent the `Stepper.NextButton` from going to the next step on click, return either false or a `Promise` that resolves false to the `onClick` prop.
stepper-nextbutton-onclick
[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/stepper-nextbutton-onclick?file=src/App.tsx)
```tsx lines expandable theme={null}
import { Stepper, Checkbox, Flex } from "@servicetitan/anvil2";
import { useState } from "react";
function App() {
const [firstPanelValid, setFirstPanelValid] = useState(false);
const [error, setError] = useState();
const handleNextClick = () => {
if (firstPanelValid === false) {
setError("Select this checkbox to continue");
} else {
setError(undefined);
}
return firstPanelValid;
};
return (
Step 1
Step 2
{
if (e && e.target.checked) setError(undefined);
setFirstPanelValid(e?.target.checked ?? false);
}}
label="Check this box to continue"
checked={firstPanelValid}
error={!!error}
description={error}
/>
Step 2 Content
The process is complete.
);
}
export default App;
```
**Stepper Props**
```tsx theme={null}
console.log(data.currentStepId, data.currentStepIndex)}
onComplete={() => console.log("Completed")}
>
...
...
```
## `Stepper` Props
In addition to the props listed below, the `Stepper` component can accept any valid HTML `div` props.
**allowNavigateToPrevStep** `boolean`
Allows the user to navigate to previous steps by clicking the step.
**defaultIndex** `number`
The index of the step to display on mount (0-based). To start the Stepper
in the completed state with `Stepper.FinalPanel` visible and all steps
marked complete, set this to the total number of steps (e.g.
`steps.length`).
**onChange** `(data) =\> void`
The `data` object has two values: `currentStepId` and `currentStepIndex`
**onComplete** `() =\> void`
**Stepper.List Props**
```tsx theme={null}
First Step
```
## `Stepper.List` Props
The `Stepper.List` component can accept any valid HTML `div` props.
**Stepper.Panel Props**
```tsx theme={null}
Panel content
```
## `Stepper.Panel` Props
The `Stepper.Panel` component can accept any valid HTML `div` props.
**Stepper.FinalPanel Props**
```tsx theme={null}
Final panel content
```
## `Stepper.FinalPanel` Props
The `Stepper.FinalPanel` component can accept any valid HTML `div` props.
**Stepper.PrevButton Props**
```tsx theme={null}
{}} />
```
## `Stepper.PrevButton` Props
The `Stepper.PrevButton` component accepts any props that the [Button](https://anvil.servicetitan.com/docs/components/button/design) component accepts, except for `label`.
**Stepper.NextButton Props**
```tsx theme={null}
{
// Return false or Promise to prevent advancing
return false;
}}
/>
```
## `Stepper.NextButton` Props
The `Stepper.NextButton` component accepts any props that the [Button](https://anvil.servicetitan.com/docs/components/button/design) component accepts, except for `label`, and with an enhanced `onClick` prop:
**completeLabel** `string` (default: Complete)
Custom label for the complete button on the final step.
**nextLabel** `string` (default: Next)
Custom label for the next button.
**onClick** `(e: MouseEvent) =\> void | boolean | Promise\`
If the `onClick` handler returns `false` or a `Promise` that resolves to `false`,
the stepper will not advance.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.