Overview

ds-progress-steps shows a user’s position in a fixed, ordered workflow, such as account setup or checkout. Use it when the total number and order of steps are known. For continuous, percentage-based progress, use Scale.

The component only presents progress. The application must update the current-step modifier and accessible state when the user moves through the workflow.

Options

Basic usage

Use an ordered list (<ol>) for workflows because the steps must be completed in sequence. An unordered list (<ul>) is also supported, but does not communicate the sequence as clearly. Each step must be an <li> directly inside the list. The component supports a maximum of 10 steps.

Indicating progress

Add a numbered modifier from --1 to --10 to identify the current step. Steps before the selected step are displayed as completed, and steps after it are displayed as incomplete. The modifier must correspond to an existing list item.

When the current step changes, also move aria-current="step" to the matching list item. See Accessibility for the recommended markup.

Indent

Use global --indent-* modifiers to add padding around the progress steps. Use --v-indent-* and --h-indent-* to control each axis independently. The --no-indent, --no-v-indent, and --no-h-indent modifiers remove the corresponding padding.

Gap

Use global --gap-* modifiers to control spacing in both directions. Use --v-gap-* to change the space between indicators and labels, or --h-gap-* to change the horizontal space between steps.

Label alignment

Add --middle to vertically center labels when their heights differ.

Add --bottom to align the bottom edge of the labels instead.

Component colors

Apply an SDS --color-* modifier to the list to change the completed progress line and current-step indicator and label.

Apply a color modifier to an individual <li> to override the color when that item is the current step. Item colors can be combined with a list color to provide a default and step-specific overrides.

Do not use color alone to communicate the current or completed state.

Icons

Apply an SDS --icon-* modifier to an <li> to replace its standard indicator with an icon. Keep the step label visible so the icon is supplementary.

Apply an icon size modifier to the list to set the default size for every icon indicator. A size modifier on an individual <li> overrides that default.

Styles

Custom styles exist for specific use cases.

Striped

Add --striped to display incomplete progress lines with a 3px striped style. Completed lines remain solid.

Vertical

Add --vertical to arrange the steps vertically. Use this style when horizontal space is limited or step labels need more room.

The vertical style can be combined with icon modifiers.

Accessibility

• Prefer an <ol> so assistive technologies receive the order and number of steps.
• Add aria-current="step" to the current <li>. Only one step should have this attribute, and it must stay synchronized with the numbered modifier on the list.
• Add visually hidden text when completed status needs to be announced. Keep labels visible and do not rely on color or icons alone.
• If completed steps link back to earlier pages, use real <a> elements and preserve any information the user has already entered.
• For multi-page workflows, include the current position, such as “Step 3 of 5,” in the page title or main heading as well as in the progress steps.

See the W3C guidance for multi-page form progress indicators and aria-current.

Manifest

The component manifest describes this component's API: its modifiers, structure, data attributes, CSS custom properties, accessibility notes, and example markup. It is consumed by tooling such as AI assistants and code generators.

Latest version: https://assets.soracom.io/sds/3.39.12/ds-progress-steps/manifest.json?v=3.39.12