Exploration: StepList

[AwelTeam]

I recently vibe-coded a prototype to explore the use cases we have at my company (checkout/wizard flows, setup checklists, compact inline progress in tables/lists, async transitions, server validation errors, etc.).

I’m sharing it here purely as input for discussion. Happy for the team to take, ignore, or reshape any of the ideas.

Goals the prototype tried to cover

• Collection-based / composable API that feels native to React Aria (<StepList> + <Item key=…>), with controlled/uncontrolled selectedKey + onSelectionChange.
• Steps before the selected key are complete and become real, keyboard-operable links (so users can jump back).
• The selected step gets aria-current="step".
• Steps after it are non-navigable (aria-disabled) — you can’t skip ahead by clicking, only via Back/Next or programmatic onSelectionChange.
• isReadOnly turns the whole thing into a pure progress indicator (no navigation).
• Support for both horizontal and vertical layouts, plus a compact type="inline" variant meant to sit inside list rows / table cells (dots only; labels live in title + screen-reader text).
• Per-step and list-level loading, disabled, and validation error states (errors keyed by step key, similar shape to React Aria Form validationErrors).
• Custom icons, descriptions, sizes (S–XL), separator styles (line / dashed / arrow), and reverse sequence..
• A thin StepListPanel wrapper that wires the same selection state to Back / Next buttons.
• A presentational skeleton for the “we don’t know the steps yet” loading state.

API sketch (high level)

<StepList
  selectedKey={key}
  onSelectionChange={setKey}
  orientation="horizontal" | "vertical"
  type="default" | "inline"
  size="S" | "M" | "L" | "XL"
  separator="line" | "dashed" | "arrow"
  sequence="positive" | "reverse"
  isReadOnly
  isDisabled
  isLoading
  validationErrors={{ pay: "…" }}
>
  <Item key="details">Details</Item>
  <Item key="offers" icon={<Gift size={12} />} description="…">
    Select offers
  </Item>
  …
</StepList>

Completed steps are focusable/clickable; the current step is announced via aria-current="step"; future steps are not interactive. Status prefixes (“Completed:”, “Not completed:”, “Loading:”, “Error:”) are visually hidden and only spoken by AT. Focused links get a live region so status changes under the cursor are announced.

Demo / code

The full prototype is available if useful: stackblitz

Thanks for the work you do on React Aria. Looking forward to whatever the official component ends up looking like — and if any of these use cases are helpful while you’re shaping the API, even better.

Also the react-ui-roundup has a lot of other examples of Steppers that might be interesting or useful points of reference to you while you're developing it.

[snowystinger]

We started a StepList component a while back. You can find the source here
https://github.com/adobe/react-spectrum/blob/main/packages/%40adobe/react-spectrum/src/steplist/StepList.tsx
It has aria and stately hooks as well, all pre-release.
And here's stories with a similar API to what you outlined https://github.com/adobe/react-spectrum/blob/main/packages/%40adobe/react-spectrum/stories/steplist/StepList.stories.tsx

We haven't had the time or priority to finish it up.