Lily Design System™

Step List

A step list is an ordered list of step items showing progress through a multi-step process. It uses a semantic <ol> element so screen readers announce the count and order of steps.

Use it for wizards, checkout flows, onboarding tours, or any sequence of stages where the user can see their position relative to the whole.

Example

StepList
Show demo markup 
<div class="step-list" aria-label="an ordered list of step items showing progress through a multi-step process">StepList</div>
Usage example 
<script lang="ts">
  import StepList from './StepList.svelte';
  import StepListItem from '../StepListItem/StepListItem.svelte';
</script>

<StepList label="Checkout" current={1}>
  <StepListItem status="finished">Cart</StepListItem>
  <StepListItem status="in-progress" current>Shipping</StepListItem>
  <StepListItem status="waiting">Payment</StepListItem>
</StepList>
Show Svelte source 
// In your Svelte component:
import StepList from "lily-design-system-svelte-headless/components/StepList/StepList.svelte";

<StepList>
  <!-- list children -->
</StepList>

Usage

<StepList label="Onboarding" current={2}>
  <StepListItem status="finished">Sign up</StepListItem>
  <StepListItem status="finished">Verify email</StepListItem>
  <StepListItem status="in-progress" current>Set preferences</StepListItem>
  <StepListItem status="waiting">Done</StepListItem>
</StepList>

Composition

Step List is the parent of Step List Items in the *List/*ListItem pattern.

<StepList label="Checkout" current={1}>
  <StepListItem status="finished">Cart</StepListItem>
  <StepListItem status="in-progress" current>Address</StepListItem>
  <StepListItem status="waiting">Payment</StepListItem>
</StepList>

Props

  • label: string (optional) -- aria-label
  • current: number (optional) -- 0-based index of the current step (data-current hook)
  • children: slot -- step-list-item children
  • ...restProps: any additional HTML attributes

Keyboard Interactions

  • None at this level — keyboard behavior lives on any interactive children.

ARIA

  • The <ol> element provides list semantics
  • aria-label provides the accessible name when label is set
  • data-current is a CSS hook; the active item should also receive aria-current="step" via StepListItem

When to Use

  • Use to show progress through a sequence of stages (checkout, wizard, onboarding).
  • Use when users benefit from seeing where they are in the flow.

When Not to Use

  • Do not use for arbitrary unordered content — use a regular list.
  • Do not use for navigation menus — use a navigation list or breadcrumb.

Headless

Renders an <ol> with no styling. The orientation, connector lines, status colors, and visual indicators are entirely the consumer's responsibility.

Styles

Consumer CSS targets the step-list class. Use data-current to drive position-based styling. Provide horizontal or vertical orientation as needed.

Testing

  • Verify the component renders an <ol> element with class step-list
  • Verify aria-label is set when label is provided
  • Verify data-current reflects the current prop when provided
  • Verify children render in document order

Advice

  • Designers: Decide whether to show the user's position via data-current styling or a separate visual indicator. Keep step labels short.
  • Developers: Pass the 0-based index via the current prop so consumer CSS can target the active step. Use StepListItem current to apply aria-current="step".

Implementation Notes

  • Renders a semantic <ol class="step-list"> element
  • aria-label is set when the optional label prop is provided
  • data-current is set when the optional current prop is provided
  • Children are typically step-list-item components
  • The <ol> provides list semantics; no extra ARIA role required

Related components

  • step-list-item — one step in a step list with status of waiting, in progress, finished, or error

References

  • WAI-ARIA Group Role: https://www.w3.org/TR/wai-aria-1.2/#group
  • Ant Design Steps: https://ant.design/components/steps

Canonical contract

Generated from this component's canonical metadata — the machine-checked source the implementations are held to.

Metadata

  • Component: step-list
  • PascalCase: StepList
  • Description: an ordered list of step items showing progress through a multi-step process
  • Status: beta — implemented and unit-tested in all seven frameworks with an axe-clean demo page; not yet exercised in composed flows
  • HTML tag: <ol>
  • CSS class: .step-list
  • Interactive: no

ARIA

  • <ol> provides list semantics
  • aria-label provides the accessible name when label is set
  • data-current is a CSS hook for the active step index

Keyboard

  • None at this level — interactive behavior lives on children

Props

  • label: string (optional)
  • current: number (optional, 0-based index)
  • children: slot — step-list-item children
  • ...restProps: any additional HTML attributes