Steps - BEEQ Design System

BEEQ Steps component overview — Steps component overview

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. The component is named Steps (bq-steps, containing bq-step-item). BEEQ has no separate Stepper component.

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

Choose bq-tab instead of bq-steps when users switch freely between peer sections of content in any order. Use bq-steps when the sections follow a fixed order with current, completed, and error states. Choose bq-breadcrumb to show where a page sits in a site hierarchy instead.

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. Allowed type values: numeric, icon, dot. The prop has no declared default. A value outside this list falls back to numeric and logs a console warning.

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 must be visually distinct from completed and remaining steps. Allowed status values: default (default), current, completed, error, disabled. Set status on bq-step-item, not on bq-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

Allowed orientation values: horizontal (default), vertical. 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

Allowed size values: medium (default), small. Allowed divider-color values: any color token as a string (default stroke--primary). 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 Steps components 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.

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

Keyboard interaction

Each bq-step-item renders a native button.

Key	Context	Action
`Tab`	Any	Moves focus to the next enabled step item
`Shift` + `Tab`	Any	Moves focus to the previous enabled step item
`Enter`	Enabled step item focused, not current	Emits `bqClick` and sets the step item as current
`Space`	Enabled step item focused, not current	Emits `bqClick` and sets the step item as current

A step item with status="disabled" is not focusable and does not emit bqClick. Activating the current step item does nothing.

Rules

Rule	Strength	Verified by
Set `status="current"` on exactly one step item	MUST	manual: inspect all step statuses for exactly one current item
Pair color with text, icon shape, or description changes	MUST	manual: read step states without their colors
Mark decorative icons with `aria-hidden="true"`	MUST	manual: inspect decorative icons for aria-hidden
Provide an `aria-label` such as `Step 1` when numeric prefixes are used	MUST	manual: inspect numeric prefix accessible names
Use the `description` slot for extra context, errors, or the next action	SHOULD	manual: read descriptions for context, errors and next actions

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`

Invalid combinations

Combination	Strength	Result
`type`, `size`, `orientation` or `divider-color` on a `bq-step-item` inside `bq-steps`	SHOULD NOT	The parent overwrites these values on every step item

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`

Hide CSS variables

Variable	Description	Default
`--bq-step-item--background-hover`	Base colour of the step item hover state background (mixed with `--bq-hover`)	`var(--bq-ui--secondary)`
`--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-ui--secondary)`
`--bq-step-item--prefix-num-bg-color-current`	Prefix number background color for the current state	`var(--bq-ui--brand)`
`--bq-step-item--prefix-num-bg-color-completed`	Prefix number background color for the completed state	`var(--bq-ui--success-alt)`
`--bq-step-item--prefix-num-bg-color-error`	Prefix number background color for the error state	`var(--bq-ui--danger-alt)`
`--bq-step-item--prefix-num-text-color`	Prefix number text color	`var(--bq-text--primary)`
`--bq-step-item--prefix-num-text-color-current`	Prefix number text color for the current state	`var(--bq-text--on-brand)`
`--bq-step-item--prefix-num-text-color-completed`	Prefix number text color for the completed state	`var(--bq-text--success)`
`--bq-step-item--prefix-num-text-color-error`	Prefix number text color for the error state	`var(--bq-text--danger)`
`--bq-step-item--title-color`	Title text color	`var(--bq-text--primary)`
`--bq-step-item--title-color-current`	Title text color for the current state	`var(--bq-text--brand)`
`--bq-step-item--description-color`	Description text color	`var(--bq-text--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

​Keyboard interaction

​Rules

​API reference

​Properties

​bq-steps

​bq-step-item

​Invalid combinations

​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

Keyboard interaction

Rules

API reference

Properties

`bq-steps`

`bq-step-item`

Invalid combinations

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