Dots

Steps List

PreviousNext

Numbered instructions with a title, an optional description, and an optional action per step.

  1. Copy the code
    It works once and expires in 12 months
    Gift card codeX7KQ-92MP-4TRA
  2. Open the store app
    Account, then Redeem gift card
  3. Paste the code
    The balance shows up within a minute
"use client"

import { Button } from "@/components/ui/button"

The StepsList component shows numbered instructions the user follows outside the current screen: how to redeem a gift card, how to add a card to a phone wallet, or what happens after a transfer. Each step has a title, an optional description, and an optional action such as a copy or open button. It is static content; for the progress of a flow the user is in right now, use Step Header instead.

Installation

pnpm dlx shadcn@latest add @dots/steps-list

Usage

import { StepsList, StepsListItem } from "@/components/ui/steps-list"
<StepsList aria-label="How to redeem">
  <StepsListItem title="Copy the code" />
  <StepsListItem
    title="Open the store app"
    description="Account, then Redeem gift card"
  />
  <StepsListItem title="Paste the code" />
</StepsList>

Composition

Use the following composition to build a steps list:

StepsList
└── StepsListItem
    ├── title
    ├── description
    ├── children
    └── action

Features

  • A real ordered list, so the order is conveyed by the markup and not only by the numbers
  • Numbers in muted circles, counted by CSS and hidden from assistive tech
  • start to continue the numbering from an earlier list
  • An action slot at the end of each step for a copy or open button
  • Extra content under the description through children, such as a copy field

Titles only

Keep each step to a short title when the instruction needs no detail. Add a description only where the user needs to know how or where.

  1. Open the wallet app on your phone
  2. Tap Add card
  3. Enter the card details
    Copy them from the Cards screen
  4. Confirm with the code we text you
import { StepsList, StepsListItem } from "@/components/ui/steps-list"

export function StepsListTitles() {

Action and content

Pass a control to action to place it at the end of the step, for example a button that opens another app. Put extra content such as a Copy Field in children; it renders under the description. See the demo at the top of this page.

<StepsListItem
  title="Open the store app"
  description="Account, then Redeem gift card"
  action={
    <Button size="sm" variant="secondary">
      Open
    </Button>
  }
/>

Start

Set start to continue the numbering, for example when the steps are split across two sections of a screen.

  1. Wait for the money to arrive
    Usually within one business day
  2. Check your balance
    The amount shows up in USD
import { StepsList, StepsListItem } from "@/components/ui/steps-list"

export function StepsListStart() {

Accessibility

StepsList renders an <ol> with role="list", so Safari keeps list semantics after list-style: none. Screen readers announce the number of steps and the position of each one. The number circles are aria-hidden, so the number is not read twice.

Label the list

When the list has no visible heading right above it, give it an aria-label such as "How to redeem". When it does, point aria-labelledby at the heading instead.

Label actions

The action is your own control. Give it text or an aria-label that names the target, such as "Copy gift card code", when the step title alone does not make it clear.

API Reference

StepsList

The ordered list.

PropTypeDefaultDescription
startnumber-The number of the first step. Shifts the visible numbers too.
classNamestring-Additional classes to apply to the list.
...propsOmit<React.ComponentProps<"ol">, "reversed" | "type">-Props spread to the <ol>.

reversed and type are left out on purpose: the numbers are a CSS counter that follows start only.

StepsListItem

One step: a number in a muted circle, the instruction, and an optional action.

PropTypeDefaultDescription
titleReact.ReactNode-What to do, such as "Open the store app". Required.
descriptionReact.ReactNode-How or where, such as "Settings, then Redeem gift card".
actionReact.ReactNode-A control at the end of the step, such as a copy button.
childrenReact.ReactNode-Extra content under the description, such as a copy field.
classNamestring-Additional classes to apply to the <li>.
...propsOmit<React.ComponentProps<"li">, "title" | "children">-Props spread to the <li>.