feat: RAC StepList and Wizard by snowystinger · Pull Request #10794 · adobe/react-spectrum

snowystinger · 2026-10-16T05:29:12Z

Closes

From discussion, split into two components. A "readonly" StepList based on html ol and an interactive Wizard based on tabs.

✅ Pull Request Checklist:

Included link to corresponding React Spectrum GitHub Issue.
Added/updated unit tests and storybook for this change (for new code or code which already has tests).
Filled out test instructions.
Updated documentation (if it already exists for this component).
Looked at the Accessibility Practices for this feature - Aria Practices
I understand every change in this PR and can explain why it's there.
If AI-assisted, I followed our AI contribution guidance and pointed my assistant at AGENTS.md.

📝 Test Instructions:

🧢 Your Project:

rspbot · 2026-10-16T05:35:20Z

Build successful! 🎉

reidbarber · 2026-10-16T15:00:59Z

+    <InternalStepListContext.Provider value={{selectedId, groupId}}>
+      <dom.ol
+        {...mergeProps(DOMProps, renderProps)}
+        role="list"


Are the roles needed here, aren't they implicit?

Oh, TIL Safari removes semantics when you add list-style: none https://www.havardbrynjulfsen.design/writing/a-new-way-to-remove-list-styles-in-safari

yeah... that was a really annoying one to track down and fix, I think it's easier than the strange display empty string in that blog, though another interesting approach. Can't ensure it for RAC though since we are generally style-less

reidbarber · 2026-10-16T15:09:15Z

+
+// Need this so I can get an id on the contents so that the announcement makes sense. It lands on this element, not the `li` itself.
+export const StepListItemContent = /*#__PURE__*/ (forwardRef as forwardRefType)(
+  function StepListItemContent(props: StepListItemContentProps, ref: ForwardedRef<HTMLDivElement>) {


Should this have render props?

Honestly, I'm still trying to get rid of this component entirely, open to ideas. One idea I had was using Text and its context.

nwidynski · 2026-10-18T21:04:30Z

+        {...DOMProps}
+        ref={objRef}
+        id={id}
+        role="link" // No role === default group which means three arrow keys to get through each item


img, perhaps with localized aria-roledescription, to avoid VO+Space announcement?

yeah, both of them feel like a lie :-/ but i like the idea of img, less implied interaction. I'd still like for people to be able to pass a link in here (Step by step example) and neither link nor img would allow for that

tested some more with img and actual links, I think it's a better experience with img, lets users know it's not interactive and it's just representing a future step I think. I'll get our a11y team to review it as well, but tentatively moving to it now.

rspbot · 2026-10-19T05:13:47Z

Build successful! 🎉

rspbot · 2026-10-23T02:09:54Z

Build successful! 🎉

rspbot · 2026-10-23T07:20:58Z

Build successful! 🎉

rspbot · 2026-11-06T17:47:50Z

Build successful! 🎉

snowystinger · 2026-11-06T18:55:07Z

+                  </span>
+                )}
+                {/* Every step has an href, but only completed steps can be navigated back to. */}
+                <StepListItemContent href={isCompleted ? step.href : undefined}>


StepListItemLink? It can be either a link or not depending if an href is supplied

snowystinger · 2026-11-06T22:58:10Z

@@ -0,0 +1,255 @@
+/*


Which should be Stepper and which should be Wizard
See: https://reui.io/docs/components/base/stepper guidelines on when not to use to find link to wizard as well

Right now ours are inverse

snowystinger · 2026-11-06T23:23:51Z

+/**
+ * A StepList displays the steps of a multi step process, and which of them the user has completed.
+ */
+export const StepList = /*#__PURE__*/ (forwardRef as forwardRefType)(function StepList<T>(


Do we want renderProps here? what would be useful states/values/properties to send into it

snowystinger · 2026-11-06T23:37:57Z

+
+const StepListItemContext = createContext<{hiddenId: string | undefined} | undefined>(undefined);
+
+export const StepListItemContent = /*#__PURE__*/ (forwardRef as forwardRefType)(


Didn't want to use Link directly because I thought that might be more confusing since an href is not required. Link would theoretically just render a span in that case.

I also wanted element structure parity between the non-link and link cases to make it easier to style

However, I need other opinions. See the stories to get an idea of how it's used with and without hrefs.

snowystinger · 2026-11-07T00:13:06Z

+ * and is never rolled back unless it's in a controlled state,
+ * so previously reached steps stay navigable after navigating backwards.
+ */
+export function useWizardState(options: WizardStateOptions): WizardState {


I will move these out to react-aria, I've kept them here for ease of iteration and hopefully review

follow up, should I build this based on RAC Tabs or base it instead on the react aria/stately hooks and have wizard be it's own RAC and the hooks just call the tabs hooks

rspbot · 2026-11-10T21:38:58Z

Build successful! 🎉

rspbot · 2026-11-11T00:20:52Z

Build successful! 🎉

rspbot · 2026-11-11T01:04:24Z

Build successful! 🎉

rspbot · 2026-11-11T03:18:05Z

Build successful! 🎉

rspbot · 2026-11-11T03:18:07Z

## API Changes

react-aria-components

/react-aria-components:StepList

+StepList <T> {
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  children?: ReactNode | (T) => ReactNode
+  className?: string = 'react-aria-StepList'
+  dependencies?: ReadonlyArray<any>
+  items?: Iterable<T>
+  render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>
+  selectedKey: Key
+  slot?: string | null
+  style?: CSSProperties
+}

/react-aria-components:StepListContext

+StepListContext {
+  UNTYPED
+}

/react-aria-components:StepListItem

+StepListItem {
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  children?: ChildrenOrFunction<StepListItemRenderProps>
+  className?: ClassNameOrFunction<StepListItemRenderProps> = 'react-aria-StepListItem'
+  id?: Key
+  render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, StepListItemRenderProps>
+  style?: StyleOrFunction<StepListItemRenderProps>
+}

/react-aria-components:StepListItemContent

+StepListItemContent {
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  children?: ReactNode
+  className?: string
+  download?: boolean | string
+  href?: Href
+  hrefLang?: string
+  id?: string
+  ping?: string
+  referrerPolicy?: HTMLAttributeReferrerPolicy
+  rel?: string
+  render?: (DetailedHTMLProps<LinkWithRequiredHref, HTMLAnchorElement> | React.JSX.IntrinsicElements[keyof React.JSX.IntrinsicElements], undefined) => ReactElement
+  routerOptions?: RouterOptions
+  style?: CSSProperties
+  target?: HTMLAttributeAnchorTarget
+}

/react-aria-components:Wizard

+Wizard {
+  allowsRandomAccess?: boolean
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  children?: ReactNode
+  className?: ClassNameOrFunction<TabsRenderProps> = 'react-aria-Wizard'
+  defaultLastCompletedStep?: Key
+  defaultSelectedKey?: Key
+  disabledKeys?: Iterable<Key>
+  id?: string
+  isDisabled?: boolean
+  keyboardActivation?: 'automatic' | 'manual' = 'automatic'
+  lastCompletedStep?: Key | null
+  onLastCompletedStepChange?: (Key | null) => void
+  onSelectionChange?: (Key) => void
+  orientation?: Orientation = 'horizontal'
+  render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabsRenderProps>
+  selectedKey?: Key | null
+  slot?: string | null
+  style?: StyleOrFunction<TabsRenderProps>
+}

/react-aria-components:WizardStepList

+WizardStepList <T extends {}> {
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  children?: ReactNode | ({}) => ReactNode
+  className?: ClassNameOrFunction<TabListRenderProps> = 'react-aria-WizardStepList'
+  dependencies?: ReadonlyArray<any>
+  items?: Iterable<{}>
+  render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabListRenderProps>
+  style?: StyleOrFunction<TabListRenderProps>
+}

/react-aria-components:WizardStep

+WizardStep {
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  children?: ChildrenOrFunction<T>
+  className?: ClassNameOrFunction<WizardStepRenderProps> = 'react-aria-WizardStep'
+  download?: boolean | string
+  href?: Href
+  hrefLang?: string
+  id?: Key
+  isDisabled?: boolean
+  onBlur?: (FocusEvent<Target>) => void
+  onClick?: (MouseEvent<FocusableElement>) => void
+  onFocus?: (FocusEvent<Target>) => void
+  onFocusChange?: (boolean) => void
+  onHoverChange?: (boolean) => void
+  onHoverEnd?: (HoverEvent) => void
+  onHoverStart?: (HoverEvent) => void
+  onPress?: (PressEvent) => void
+  onPressChange?: (boolean) => void
+  onPressEnd?: (PressEvent) => void
+  onPressStart?: (PressEvent) => void
+  onPressUp?: (PressEvent) => void
+  ping?: string
+  referrerPolicy?: HTMLAttributeReferrerPolicy
+  rel?: string
+  render?: (DetailedHTMLProps<LinkWithRequiredHref, HTMLAnchorElement> | React.JSX.IntrinsicElements[keyof React.JSX.IntrinsicElements], WizardStepRenderProps) => ReactElement
+  routerOptions?: RouterOptions
+  style?: StyleOrFunction<T>
+  target?: HTMLAttributeAnchorTarget
+}

/react-aria-components:WizardPanels

+WizardPanels <T extends {}> {
+  children?: ReactNode | ({}) => ReactNode
+  className?: string = 'react-aria-WizardPanels'
+  dependencies?: ReadonlyArray<any>
+  items?: Iterable<{}>
+  render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>
+  style?: CSSProperties
+}

/react-aria-components:WizardPanel

+WizardPanel {
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  children?: ChildrenOrFunction<TabPanelRenderProps>
+  className?: ClassNameOrFunction<TabPanelRenderProps> = 'react-aria-WizardPanel'
+  id?: Key
+  render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabPanelRenderProps>
+  shouldForceMount?: boolean = false
+  style?: StyleOrFunction<TabPanelRenderProps>
+}

/react-aria-components:StepListProps

+StepListProps <T> {
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  children?: ReactNode | (T) => ReactNode
+  className?: string = 'react-aria-StepList'
+  dependencies?: ReadonlyArray<any>
+  items?: Iterable<T>
+  render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>
+  selectedKey: Key
+  slot?: string | null
+  style?: CSSProperties
+}

/react-aria-components:StepListItemProps

+StepListItemProps {
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  children?: ChildrenOrFunction<StepListItemRenderProps>
+  className?: ClassNameOrFunction<StepListItemRenderProps> = 'react-aria-StepListItem'
+  id?: Key
+  render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, StepListItemRenderProps>
+  style?: StyleOrFunction<StepListItemRenderProps>
+}

/react-aria-components:StepListItemRenderProps

+StepListItemRenderProps {
+  isCompleted: boolean
+  isCurrent: boolean
+  stepNumber: number
+}

/react-aria-components:StepListItemContentProps

+StepListItemContentProps {
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  children?: ReactNode
+  className?: string
+  download?: boolean | string
+  href?: Href
+  hrefLang?: string
+  id?: string
+  ping?: string
+  referrerPolicy?: HTMLAttributeReferrerPolicy
+  rel?: string
+  render?: (DetailedHTMLProps<LinkWithRequiredHref, HTMLAnchorElement> | React.JSX.IntrinsicElements[keyof React.JSX.IntrinsicElements], undefined) => ReactElement
+  routerOptions?: RouterOptions
+  style?: CSSProperties
+  target?: HTMLAttributeAnchorTarget
+}

/react-aria-components:WizardProps

+WizardProps {
+  allowsRandomAccess?: boolean
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  children?: ReactNode
+  className?: ClassNameOrFunction<TabsRenderProps> = 'react-aria-Wizard'
+  defaultLastCompletedStep?: Key
+  defaultSelectedKey?: Key
+  disabledKeys?: Iterable<Key>
+  id?: string
+  isDisabled?: boolean
+  keyboardActivation?: 'automatic' | 'manual' = 'automatic'
+  lastCompletedStep?: Key | null
+  onLastCompletedStepChange?: (Key | null) => void
+  onSelectionChange?: (Key) => void
+  orientation?: Orientation = 'horizontal'
+  render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabsRenderProps>
+  selectedKey?: Key | null
+  slot?: string | null
+  style?: StyleOrFunction<TabsRenderProps>
+}

/react-aria-components:WizardStepListProps

+WizardStepListProps <T> {
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  children?: ReactNode | (T) => ReactNode
+  className?: ClassNameOrFunction<TabListRenderProps> = 'react-aria-WizardStepList'
+  dependencies?: ReadonlyArray<any>
+  items?: Iterable<T>
+  render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabListRenderProps>
+  style?: StyleOrFunction<TabListRenderProps>
+}

/react-aria-components:WizardStepProps

+WizardStepProps {
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  children?: ChildrenOrFunction<T>
+  className?: ClassNameOrFunction<WizardStepRenderProps> = 'react-aria-WizardStep'
+  download?: boolean | string
+  href?: Href
+  hrefLang?: string
+  id?: Key
+  isDisabled?: boolean
+  onBlur?: (FocusEvent<Target>) => void
+  onClick?: (MouseEvent<FocusableElement>) => void
+  onFocus?: (FocusEvent<Target>) => void
+  onFocusChange?: (boolean) => void
+  onHoverChange?: (boolean) => void
+  onHoverEnd?: (HoverEvent) => void
+  onHoverStart?: (HoverEvent) => void
+  onPress?: (PressEvent) => void
+  onPressChange?: (boolean) => void
+  onPressEnd?: (PressEvent) => void
+  onPressStart?: (PressEvent) => void
+  onPressUp?: (PressEvent) => void
+  ping?: string
+  referrerPolicy?: HTMLAttributeReferrerPolicy
+  rel?: string
+  render?: (DetailedHTMLProps<LinkWithRequiredHref, HTMLAnchorElement> | React.JSX.IntrinsicElements[keyof React.JSX.IntrinsicElements], WizardStepRenderProps) => ReactElement
+  routerOptions?: RouterOptions
+  style?: StyleOrFunction<T>
+  target?: HTMLAttributeAnchorTarget
+}

/react-aria-components:WizardStepRenderProps

+WizardStepRenderProps {
+  isCompleted: boolean
+  isCurrent: boolean
+  isDisabled: boolean
+  isFocusVisible: boolean
+  isFocused: boolean
+  isHovered: boolean
+  isPressed: boolean
+  isSelected: boolean
+  stepNumber: number
+}

/react-aria-components:WizardPanelsProps

+WizardPanelsProps <T> {
+  children?: ReactNode | (T) => ReactNode
+  className?: string = 'react-aria-WizardPanels'
+  dependencies?: ReadonlyArray<any>
+  items?: Iterable<T>
+  render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>
+  style?: CSSProperties
+}

/react-aria-components:WizardPanelProps

+WizardPanelProps {
+  aria-describedby?: string
+  aria-details?: string
+  aria-label?: string
+  aria-labelledby?: string
+  children?: ChildrenOrFunction<TabPanelRenderProps>
+  className?: ClassNameOrFunction<TabPanelRenderProps> = 'react-aria-WizardPanel'
+  id?: Key
+  render?: DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabPanelRenderProps>
+  shouldForceMount?: boolean = false
+  style?: StyleOrFunction<TabPanelRenderProps>
+}

/react-aria-components:WizardStepAria

+WizardStepAria {
+  isCompleted: boolean
+  isCurrent: boolean
+  stepNumber: number
+}

/react-aria-components:WizardState

+WizardState <T> {
+  collection: Collection<Node<T>>
+  disabledKeys: Set<Key>
+  lastCompletedStep: Key | null
+  selectedKey: Key | null
+  setSelectedKey: (Key) => void
+}

/react-aria-components:WizardStateOptions

+WizardStateOptions <T> {
+  allowsRandomAccess?: boolean
+  collection: Collection<Node<T>>
+  defaultLastCompletedStep?: Key
+  defaultSelectedKey?: Key
+  disabledKeys?: Iterable<Key>
+  lastCompletedStep?: Key | null
+  onLastCompletedStepChange?: (Key | null) => void
+  onSelectionChange?: (Key) => void
+  selectedKey?: Key | null
+}

rspbot · 2026-11-11T03:18:09Z

Agent Skills Changes

Added (4)

react-aria/agent-skills/react-aria/references/components/StepList.md $\color{green}{+652}$
react-aria/agent-skills/react-aria/references/components/Wizard.md $\color{green}{+918}$
s2/agent-skills/react-spectrum-s2/references/react-aria/components/StepList.md $\color{green}{+652}$
s2/agent-skills/react-spectrum-s2/references/react-aria/components/Wizard.md $\color{green}{+918}$

Modified (12)

react-aria/agent-skills/index.json $\color{green}{+1}$ $\color{red}{-1}$
react-aria/agent-skills/react-aria.tar.gz
react-aria/agent-skills/react-aria/SKILL.md $\color{green}{+1}$ $\color{red}{-1}$
react-aria/agent-skills/react-aria/references/components/Separator/useSeparator.md $\color{green}{+1}$ $\color{red}{-1}$
react-aria/agent-skills/react-aria/references/llms.txt $\color{green}{+2}$
s2/agent-skills/index.json $\color{green}{+3}$ $\color{red}{-3}$
s2/agent-skills/migrate-react-spectrum-v3-to-s2.tar.gz
s2/agent-skills/react-spectrum-s2.tar.gz
s2/agent-skills/react-spectrum-s2/references/guides/ai-components.md $\color{red}{-17}$
s2/agent-skills/react-spectrum-s2/references/react-aria/components/Separator/useSeparator.md $\color{green}{+1}$ $\color{red}{-1}$
s2/agent-skills/react-spectrum-s2/references/react-aria/llms.txt $\color{green}{+2}$
s2/agent-skills/spectrum-audit.tar.gz

Install

React Spectrum S2:

npx skills add https://d1pzu54gtk2aed.cloudfront.net/pr/7c66174166563d9ca7da37fa205a97ff9844d6af/

React Aria:

npx skills add https://d5iwopk28bdhl.cloudfront.net/pr/7c66174166563d9ca7da37fa205a97ff9844d6af/

feat: StepList round two

64b33ec

github-actions Bot added needs translations RAC labels Oct 16, 2026

reidbarber reviewed Oct 16, 2026

View reviewed changes

nwidynski reviewed Oct 18, 2026

View reviewed changes

Comment thread packages/react-aria-components/src/StepList.tsx Resolved

nwidynski reviewed Oct 18, 2026

View reviewed changes

add Wizard

19730be

update readonly to collection and support anchor rendering, add tests

e2fd60b

Fix old storybook

83487e7

yihuiliao added the rsp-core label Oct 30, 2026

Merge branch 'main' into wizard-and-stepper

e6acaae

snowystinger added 3 commits November 6, 2026 14:56

update to actual API in tests

7e41f3b

Merge branch 'main' into wizard-and-stepper

3c726d1

remove comment

2de527a

snowystinger commented Nov 7, 2026

View reviewed changes

snowystinger added 3 commits November 6, 2026 17:04

add wizard tests and remove useEffect sync in Wizard

b6a52df

Merge branch 'main' into wizard-and-stepper

b514917

fix lint

2f763c9

Add docs and exports for readonly steplist

0617887

Make examples better on small screens

cdb5114

add wizard docs

9f2580f

snowystinger marked this pull request as ready for review November 11, 2026 02:17

refactor and fix typecheck

7c66174

snowystinger mentioned this pull request Nov 11, 2026

feat: Rac step list #10601

Closed

7 tasks

snowystinger changed the title ~~feat: StepList round two~~ feat: RAC StepList and Wizard Nov 11, 2026


		const StepListItemContext = createContext<{hiddenId: string \| undefined} \| undefined>(undefined);

		export const StepListItemContent = /#__PURE__/ (forwardRef as forwardRefType)(

Conversation

snowystinger commented Oct 16, 2026

✅ Pull Request Checklist:

📝 Test Instructions:

🧢 Your Project:

Uh oh!

rspbot commented Oct 16, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

snowystinger Oct 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nwidynski Oct 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rspbot commented Oct 19, 2026

Uh oh!

rspbot commented Oct 23, 2026

Uh oh!

rspbot commented Oct 23, 2026

Uh oh!

rspbot commented Nov 6, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rspbot commented Nov 10, 2026

Uh oh!

rspbot commented Nov 11, 2026

Uh oh!

rspbot commented Nov 11, 2026

Uh oh!

rspbot commented Nov 11, 2026

Uh oh!

rspbot commented Nov 11, 2026

react-aria-components

/react-aria-components:StepList

/react-aria-components:StepListContext

/react-aria-components:StepListItem

/react-aria-components:StepListItemContent

/react-aria-components:Wizard

/react-aria-components:WizardStepList

/react-aria-components:WizardStep

/react-aria-components:WizardPanels

/react-aria-components:WizardPanel

/react-aria-components:StepListProps

/react-aria-components:StepListItemProps

/react-aria-components:StepListItemRenderProps

/react-aria-components:StepListItemContentProps

/react-aria-components:WizardProps

/react-aria-components:WizardStepListProps

/react-aria-components:WizardStepProps

/react-aria-components:WizardStepRenderProps

/react-aria-components:WizardPanelsProps

/react-aria-components:WizardPanelProps

/react-aria-components:WizardStepAria

/react-aria-components:WizardState

snowystinger Oct 17, 2026 •

edited

Loading

nwidynski Oct 18, 2026 •

edited

Loading