Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -296,7 +296,8 @@
".storybook-s2/**",
"packages/dev/s2-docs/**",
"starters/**",
"packages/react-aria-components/stories/Sheet.css"
"packages/react-aria-components/stories/Sheet.css",
"packages/react-aria-components/stories/StepList.css"
]
},
"drafts": {
Expand Down
172 changes: 172 additions & 0 deletions packages/dev/s2-docs/pages/react-aria/StepList.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,172 @@
import {Layout} from '../../src/Layout';
export default Layout;

import docs from 'docs:react-aria-components';
import '../../tailwind/tailwind.css';
import {InlineAlert, Heading, Content} from '@react-spectrum/s2';

export const tags = ['wizard', 'stepper', 'steps', 'progress', 'steplist'];
export const version = 'alpha';
export const description = 'Displays the steps of a multi-step process, and which of them the user has completed.';

# StepList

<PageDescription>{docs.exports.StepList.description}</PageDescription>

<ExampleSwitcher>
```tsx render docs={docs.exports.StepList} links={docs.links} props={[]} type="vanilla" files={["starters/docs/src/StepList.tsx", "starters/docs/src/StepList.css"]}
"use client";
import {StepList, StepListItem} from 'vanilla-starter/StepList';

<StepList aria-label="Checkout" selectedKey="payment">
<StepListItem id="cart">Cart</StepListItem>
<StepListItem id="shipping">Shipping</StepListItem>
<StepListItem id="payment">Payment</StepListItem>
<StepListItem id="review">Review</StepListItem>
</StepList>
```

```tsx render docs={docs.exports.StepList} links={docs.links} props={[]} type="tailwind" files={["starters/tailwind/src/StepList.tsx"]}
"use client";
import {StepList, StepListItem} from 'tailwind-starter/StepList';

<StepList aria-label="Checkout" selectedKey="payment">
<StepListItem id="cart">Cart</StepListItem>
<StepListItem id="shipping">Shipping</StepListItem>
<StepListItem id="payment">Payment</StepListItem>
<StepListItem id="review">Review</StepListItem>
</StepList>
```

</ExampleSwitcher>

## Content

`StepList` follows the [Collection Components API](collections?component=StepList), accepting both static and dynamic collections. This example shows a dynamic collection, passing a list of objects to the `items` prop, and a function to render the children.

```tsx render
"use client";
import {StepList, StepListItem} from 'vanilla-starter/StepList';

let steps = [
{id: 'account', label: 'Account'},
{id: 'profile', label: 'Profile'},
{id: 'settings', label: 'Settings'},
{id: 'confirm', label: 'Confirm'}
];

<StepList
aria-label="Sign up"
/*- begin highlight -*/
items={steps}
/*- end highlight -*/
selectedKey="profile">
{step => <StepListItem>{step.label}</StepListItem>}
</StepList>
```

<InlineAlert variant="notice">
<Heading>Accessibility</Heading>
<Content>Provide an `aria-label` or `aria-labelledby` that describes the process, such as "Checkout". Each step announces whether it is completed, current, or not completed, and the current step is marked with `aria-current="step"`.</Content>
</InlineAlert>

### Links

Use the `href` prop on a `<StepListItemContent>` to create a link to a step. In this example, only completed steps are links, so users can go back to a previous step, but not skip ahead.

```tsx render files={["packages/dev/s2-docs/pages/react-aria/Router.tsx"]}
"use client";
import {StepList, StepListItem} from 'vanilla-starter/StepList';
import {Router, Link as RouterLink} from './Router';

<Router defaultSelectedRoute="/review">
{({selectedRoute}) => (
/*- begin highlight -*/
<StepList aria-label="Checkout" selectedKey={selectedRoute} renderLink={props => 'href' in props ? <RouterLink {...props} /> : <div {...props} />}>
{/*- end highlight -*/}
<StepListItem id="/cart" href="/cart">Cart</StepListItem>
<StepListItem id="/shipping" href="/shipping">Shipping</StepListItem>
<StepListItem id="/payment" href="/payment">Payment</StepListItem>
<StepListItem id="/review" href="/review">Review</StepListItem>
</StepList>
)}
</Router>
```

By default, links are rendered as an `<a>` element. Use the `render` prop to integrate your framework's link component.

```tsx
<StepListItemContent
href="/shipping"
render={domProps =>
'href' in domProps
? <RouterLink {...domProps} />
: <div {...domProps} />
} />
```

## Current step

Use the `selectedKey` prop to set the current step. The current step is marked with `aria-current="step"`, and the steps before it are marked as completed. Use the `data-current` and `data-completed` attributes to style them.

```tsx render
"use client";
import {StepList, StepListItem} from 'vanilla-starter/StepList';
import {Button} from 'vanilla-starter/Button';
import {useState} from 'react';

let steps = [
{id: 'cart', label: 'Cart'},
{id: 'shipping', label: 'Shipping'},
{id: 'payment', label: 'Payment'},
{id: 'review', label: 'Review'}
];

function Example() {
let [index, setIndex] = useState(1);

return (
<div style={{display: 'flex', flexDirection: 'column', alignItems: 'start', gap: 16, maxWidth: '100%'}}>
<StepList
aria-label="Checkout"
items={steps}
/*- begin highlight -*/
selectedKey={steps[index].id}>
{/*- end highlight -*/}
{step => <StepListItem>{step.label}</StepListItem>}
</StepList>
<div style={{display: 'flex', gap: 8}}>
<Button isDisabled={index === 0} onPress={() => setIndex(index - 1)}>Back</Button>
<Button isDisabled={index === steps.length - 1} onPress={() => setIndex(index + 1)}>Next</Button>
</div>
</div>
);
}
```

## StepList vs. Wizard

Use a `StepList` to show a sequence of steps in a user flow, where each step corresponds to a separate page or route.
To allow random access and let users move between the steps they have reached without losing their progress, use a [Wizard](Wizard) instead.

## API

```tsx links={{StepList: '#steplist', StepListItem: '#steplistitem', StepListItemContent: '#steplistitemcontent'}}
<StepList>
<StepListItem>
<StepListItemContent />
</StepListItem>
</StepList>
```

### StepList

<PropTable component={docs.exports.StepList} links={docs.links} showDescription />

### StepListItem

<PropTable component={docs.exports.StepListItem} links={docs.links} showDescription />

### StepListItemContent

<PropTable component={docs.exports.StepListItemContent} links={docs.links} showDescription />
178 changes: 178 additions & 0 deletions packages/dev/s2-docs/pages/react-aria/Wizard.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,178 @@
import {Layout} from '../../src/Layout';
export default Layout;

import docs from 'docs:react-aria-components';
import '../../tailwind/tailwind.css';
import {InlineAlert, Heading, Content} from '@react-spectrum/s2';

export const tags = ['stepper', 'steps', 'multi-step', 'form', 'flow'];
export const version = 'alpha';
export const description = 'Guides users through a multi-step process one step at a time.';

# Wizard

<PageDescription>{docs.exports.Wizard.description}</PageDescription>

<ExampleSwitcher>
```tsx render docs={docs.exports.Wizard} links={docs.links} props={['allowsRandomAccess']} type="vanilla" files={["starters/docs/src/Wizard.tsx", "starters/docs/src/Wizard.css"]}
"use client";
import {Wizard, WizardStepList, WizardStep, WizardPanels, WizardPanel, WizardButtons} from 'vanilla-starter/Wizard';

<Wizard/* PROPS */>
<WizardStepList aria-label="Create project">
<WizardStep id="details">Details</WizardStep>
<WizardStep id="members">Members</WizardStep>
<WizardStep id="review">Review</WizardStep>
</WizardStepList>
<WizardPanels>
<WizardPanel id="details">Name your project and choose who can see it.</WizardPanel>
<WizardPanel id="members">Invite people to work on the project with you.</WizardPanel>
<WizardPanel id="review">Check the details, then create the project.</WizardPanel>
</WizardPanels>
<WizardButtons />
</Wizard>
```

```tsx render docs={docs.exports.Wizard} links={docs.links} props={['allowsRandomAccess']} type="tailwind" files={["starters/tailwind/src/Wizard.tsx"]}
"use client";
import {Wizard, WizardStepList, WizardStep, WizardPanels, WizardPanel, WizardButtons} from 'tailwind-starter/Wizard';

<Wizard/* PROPS */>
<WizardStepList aria-label="Create project">
<WizardStep id="details">Details</WizardStep>
<WizardStep id="members">Members</WizardStep>
<WizardStep id="review">Review</WizardStep>
</WizardStepList>
<WizardPanels>
<WizardPanel id="details">Name your project and choose who can see it.</WizardPanel>
<WizardPanel id="members">Invite people to work on the project with you.</WizardPanel>
<WizardPanel id="review">Check the details, then create the project.</WizardPanel>
</WizardPanels>
<WizardButtons />
</Wizard>
```

</ExampleSwitcher>

## Content

`WizardStepList` and `WizardPanels` follow the [Collection Components API](collections?component=WizardStepList), accepting both static and dynamic collections. This example shows a dynamic collection, passing a list of objects to the `items` prop, and a function to render the children.

```tsx render
"use client";
import {Wizard, WizardStepList, WizardStep, WizardPanels, WizardPanel, WizardButtons} from 'vanilla-starter/Wizard';

let steps = [
{id: 'account', label: 'Account', content: 'Choose a username and password.'},
{id: 'profile', label: 'Profile', content: 'Add a photo and a short bio.'},
{id: 'settings', label: 'Settings', content: 'Choose which notifications you receive.'},
{id: 'confirm', label: 'Confirm', content: 'Check your details, then create your account.'}
];

<Wizard>
<WizardStepList
aria-label="Sign up"
/*- begin highlight -*/
items={steps}>
{/*- end highlight -*/}
{step => <WizardStep>{step.label}</WizardStep>}
</WizardStepList>
<WizardPanels
/*- begin highlight -*/
items={steps}>
{/*- end highlight -*/}
{step => <WizardPanel>{step.content}</WizardPanel>}
</WizardPanels>
<WizardButtons />
</Wizard>
```

<InlineAlert variant="notice">
<Heading>Accessibility</Heading>
<Content>Provide an `aria-label` or `aria-labelledby` on the `WizardStepList` that describes the process, such as "Sign up". Each step announces whether it is completed, so hide visual indicators such as step numbers and checkmarks with `aria-hidden`. Steps are selected with the <Keyboard>Enter</Keyboard> or <Keyboard>Space</Keyboard> key rather than when they receive focus, so keyboard users can review the steps without leaving the current one.</Content>
</InlineAlert>

## Current step

Use the `defaultSelectedKey` or `selectedKey` prop to set the current step. The selected key corresponds to the `id` prop of a `<WizardStep>`. Steps before the current step are marked as completed, and steps the user hasn't reached yet are disabled. Use the `data-current` and `data-completed` attributes to style them.

```tsx render
"use client";
import type {Key} from 'react-aria-components/Wizard';
import {Wizard, WizardStepList, WizardStep, WizardPanels, WizardPanel, WizardButtons} from 'vanilla-starter/Wizard';
import {useState} from 'react';

function Example() {
let [step, setStep] = useState<Key>('members');

return (
<div>
<Wizard
///- begin highlight -///
selectedKey={step}
onSelectionChange={setStep}
///- end highlight -///
>
<WizardStepList aria-label="Create project">
<WizardStep id="details">Details</WizardStep>
<WizardStep id="members">Members</WizardStep>
<WizardStep id="review">Review</WizardStep>
</WizardStepList>
<WizardPanels>
<WizardPanel id="details">Name your project and choose who can see it.</WizardPanel>
<WizardPanel id="members">Invite people to work on the project with you.</WizardPanel>
<WizardPanel id="review">Check the details, then create the project.</WizardPanel>
</WizardPanels>
<WizardButtons />
</Wizard>
<p>Current step: {step}</p>
</div>
);
}
```

Users can go back to any step they have reached, and return to where they left off. Set `allowsRandomAccess` to let users select any step. To restore saved progress, set `defaultLastCompletedStep` to the last step the user completed, or control it with the `lastCompletedStep` and `onLastCompletedStepChange` props.

## Wizard vs. StepList

Use a `Wizard` when the content of each step is shown on the same page, and users move between the steps they have reached. When each step is a separate page or route, use a [StepList](StepList) instead to show the user's progress through the process.

## API

```tsx links={{Wizard: '#wizard', WizardStepList: '#wizardsteplist', WizardStep: '#wizardstep', WizardPanels: '#wizardpanels', WizardPanel: '#wizardpanel'}}
<Wizard>
<WizardStepList>
<WizardStep />
</WizardStepList>
<WizardPanels>
<WizardPanel />
</WizardPanels>
</Wizard>
```

### Wizard

<PropTable component={docs.exports.Wizard} links={docs.links} showDescription />

### WizardStepList

<PropTable component={docs.exports.WizardStepList} links={docs.links} showDescription />

### WizardStep

<PropTable component={docs.exports.WizardStep} links={docs.links} showDescription />

### WizardPanels

<PropTable
component={docs.exports.WizardPanels}
links={docs.links}
showDescription
cssVariables={{
'--tab-panel-width': 'The width of the active panel in pixels. Useful for animations. Set when width, inline-size, or all is used in the CSS transition.',
'--tab-panel-height': 'The height of the active panel in pixels. Useful for animations. Set when height, block-size, or all is used in the CSS transition.'
}} />

### WizardPanel

<PropTable component={docs.exports.WizardPanel} links={docs.links} showDescription />
24 changes: 24 additions & 0 deletions packages/react-aria-components/exports/StepList.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
/*
* Copyright 2026 Adobe. All rights reserved.
* This file is licensed to you under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License. You may obtain a copy
* of the License at http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under
* the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
* OF ANY KIND, either express or implied. See the License for the specific language
* governing permissions and limitations under the License.
*/

// Mark as a client only package. This will cause a build time error if you try
// to import it from a React Server Component in a framework like Next.js.
import 'client-only';

export {StepList, StepListContext, StepListItem, StepListItemContent} from '../src/StepList';
export type {
StepListProps,
StepListItemProps,
StepListItemRenderProps,
StepListItemContentProps
} from '../src/StepList';
export type {Key} from '@react-types/shared';
Loading
Loading