Steps - BEEQ Design System

Steps guide users through a sequential process such as a wizard, onboarding flow, or multistep form. Use them to show progress, the current step, completed steps, and steps that still need attention.

Use bq-step-item inside bq-steps. The parent component passes type, orientation, size, and divider settings down to each step item.

When to use

Use steps when

Users need to complete a sequential, multistep process
The workflow has a clear order and progress state
Users benefit from seeing current, completed, remaining, or error states

Do not use steps when

Users can complete tasks in any order
The process has only one or two simple actions
A status message or progress bar communicates the state more clearly

Patterns

Multistep forms

Split long forms into clear stages so users can see what is complete, where they are, and what remains.

Onboarding and wizards

Guide users through setup flows where each step depends on the previous one.

Process overviews

Summarize a task, service, or project flow when readers need the full sequence before they start.

Progress tracking

Show completed, current, upcoming, blocked, or disabled stages in a process that changes over time.

Anatomy

Steps are composed of a label or prefix, title, optional description, and divider. Together they communicate position, meaning, and progress through the process.

Part	Element	Description
1	Prefix	Dot, number, or icon that visually identifies the step
2	Title	Step label that describes the task or stage
3	Description	Optional supporting text for more context
4	Divider	Connector that shows sequence between steps

Design guidelines

Label and icon

Labels describe each step, while icons provide visual cues. Use meaningful titles and reserve icons for cases where the symbol helps users understand the action or context.

Usage

Start with bq-steps and one bq-step-item for each stage. There are three types of steps: numeric, dot, and icon.

You must specify the type you want to use on bq-steps. If you don’t, the default styles will apply, but it may not match your content or design intent.

Numeric

Start with the numeric type to show a clear sequence and position in the process. Each step should have a number prefix that matches its order.

Dot

Use type="dot" for a minimal progress indicator when the sequence is clear and the step labels carry most of the meaning.

Icon

Use type="icon" when each step benefits from a recognizable symbol. Icons should support the label, not replace it.

Status

Use the status attribute to show progress and guide users through the process. The current step should be visually distinct from completed and remaining steps.

The status should be applied to the bq-step-item element. This ensures that the entire step, including the label and description, reflects the current state.

Status	Description
`default`	The default state for steps that have not been reached yet. It should be visually distinct from current and completed steps.
`current`	The step the user is currently on. It should be visually highlighted to indicate focus.
`completed`	A step that has been finished. It should be visually distinct from the current and remaining steps.
`disabled`	A step that is not available for interaction, often because a previous step has not been completed. It should be visually subdued to indicate it cannot be accessed yet.
`error`	A step that has an issue that needs attention. It should be visually distinct to indicate a problem.

Options

Orientation

Use orientation="vertical" when the process should unfold from top to bottom or when labels and descriptions need more room.

Vertical steps adapt to the height of their container. You must ensure that the container holding the steps has enough block size to allow the divider to span the desired area.

Size and divider color

Use size="small" in compact layouts. Use divider-color with a declarative color token when the connector needs a different emphasis.

Best practices

DoUse one steps component per page so the process stays clear and cohesive.

Don’tAvoid multiple steppers in the same view because they can compete for attention and disrupt the flow.

DoWrite labels that describe the task or destination for each step.

Don’tAvoid labels that only repeat the status, such as current or completed.

DoConfirm progress with status, text, and icon changes after a step is completed.

Don’tDo not rely on color alone to communicate the state of a step.

DoKeep the number of steps manageable so users feel the process is achievable.

Don’tAvoid turning long or non-linear workflows into a single rigid step sequence.

Accessibility

The bq-steps container renders with role="list", and each bq-step-item renders with role="listitem" around an interactive button. The current step maps to aria-current="step", and disabled items use the native disabled button state.

Keyboard - users can move through step items with Tab and Shift + Tab. They can activate an enabled step with Enter or Space.
Current step - set status="current" on one step item so assistive technology can announce the current position.
Status communication - pair color with text, icon shape, or description changes so users do not need color perception to understand progress.
Icons and numbers - mark decorative icons with aria-hidden="true". When numeric prefixes are used, provide an aria-label such as Step 1.
Descriptions - use the description slot when users need more context about a step, an error, or the expected next action.

API reference

Properties

`bq-steps`

Property	Attribute	Description	Type	Default
`dividerColor`	`divider-color`	Color token for the line that connects steps	`string`	`'stroke--primary'`
`orientation`	`orientation`	Direction of the steps	`'horizontal'` \| `'vertical'`	`'horizontal'`
`size`	`size`	Size of the steps	`'medium'` \| `'small'`	`'medium'`
`type`	`type`	Prefix type passed to step items	`'numeric'` \| `'icon'` \| `'dot'`	`undefined`

`bq-step-item`

Property	Attribute	Description	Type	Default
`dividerColor`	`divider-color`	Color token for the divider after this item; usually inherited from `bq-steps`	`string`	`'stroke--primary'`
`orientation`	`orientation`	Direction of the item; usually inherited from `bq-steps`	`'horizontal'` \| `'vertical'`	`'horizontal'`
`size`	`size`	Prefix size; usually inherited from `bq-steps`	`'medium'` \| `'small'`	`'medium'`
`status`	`status`	Visual and semantic state of the item	`'default'` \| `'current'` \| `'completed'` \| `'error'` \| `'disabled'`	`'default'`
`type`	`type`	Prefix type; usually inherited from `bq-steps`	`'numeric'` \| `'icon'` \| `'dot'`	`undefined`

Slots

`bq-steps`

Slot	Description
(default)	Step items

`bq-step-item`

Slot	Description
(default)	Step item title content
`prefix`	Dot, icon, or number shown before the title
`description`	Supporting text shown below the title

Shadow parts

`bq-steps`

Part	Description
`container`	Container wrapper of the Steps component
`divider-base`	Base wrapper of the divider component
`divider-dash-start`	Start dash of the divider component
`divider-dash-end`	End dash of the divider component

`bq-step-item`

Part	Description
`base`	Step item button wrapper
`title`	Step item title
`description`	Step item description

Events

`bq-step-item`

Event	Description	Type
`bqClick`	Fires when an enabled step item is clicked	`CustomEvent<HTMLBqStepItemElement>`
`bqFocus`	Fires when a step item receives focus	`CustomEvent<HTMLBqStepItemElement>`
`bqBlur`	Fires when a step item loses focus	`CustomEvent<HTMLBqStepItemElement>`

In React, prefix events with on: onBqClick, onBqFocus, onBqBlur.
In Angular, use event binding syntax: (bqClick), (bqFocus), (bqBlur).
In Vue, use the @ shorthand: @bqClick, @bqFocus, @bqBlur.

Methods

`bq-steps`

Method	Description	Returns
`setCurrentStepItem(newCurrentStep)`	Sets the provided step item as current and resets the previous current item to default	`Promise<void>`

CSS custom properties

`bq-steps`

Variable	Description	Default
`--bq-steps--divider-color`	Divider color	`var(--bq-stroke--primary)`
`--bq-steps--gap`	Gap between steps	`var(--bq-spacing-m)`

`bq-step-item`

Variable	Description	Default
`--bq-step-item--prefix-color`	Prefix icon color	`var(--bq-icon--secondary)`
`--bq-step-item--prefix-color-current`		Prefix icon color for the current state	`var(--bq-icon--brand)`
`--bq-step-item--prefix-color-completed`	Prefix icon color for the completed state	`var(--bq-icon--success)`
`--bq-step-item--prefix-color-error`	Prefix icon color for the error state	`var(--bq-icon--danger)`
`--bq-step-item--prefix-num-size`	Prefix number size	`var(--bq-spacing-xl)`
`--bq-step-item--prefix-num-bg-color`	Prefix number background color	`var(--bq-background--secondary)`

Learn more about styling with shadow parts and CSS custom properties.

Resources

Interactive playground

Explore Steps variants and states in Storybook

Source code

View the component source on GitHub

​When to use

​Patterns

Multistep forms

Onboarding and wizards

Process overviews

Progress tracking

​Anatomy

​Design guidelines

​Label and icon

​Usage

​Numeric

​Dot

​Icon

​Status

​Options

​Orientation

​Size and divider color

​Best practices

​Accessibility

​API reference

​Properties

​bq-steps

​bq-step-item

​Slots

​bq-steps

​bq-step-item

​Shadow parts

​bq-steps

​bq-step-item

​Events

​bq-step-item

​Methods

​bq-steps

​CSS custom properties

​bq-steps

​bq-step-item

​Resources

Interactive playground

Source code

When to use

Patterns

Anatomy

Design guidelines

Label and icon

Usage

Numeric

Dot

Icon

Status

Options

Orientation

Size and divider color

Best practices

Accessibility

API reference

Properties

`bq-steps`

`bq-step-item`

Slots

`bq-steps`

`bq-step-item`

Shadow parts

`bq-steps`

`bq-step-item`

Events

`bq-step-item`

Methods

`bq-steps`

CSS custom properties

`bq-steps`

`bq-step-item`

Resources