> ## Documentation Index
> Fetch the complete documentation index at: https://www.beeq.design/llms.txt
> Use this file to discover all available pages before exploring further.

# Steps

> Steps display a series of stages in a process so users can understand progress, current status, and what comes next.

![BEEQ Steps component overview](https://mintcdn.com/beeq/uQ_Kuh3HHK5CbrgS/components/images/steps/steps-overview-light.svg?fit=max\&auto=format\&n=uQ_Kuh3HHK5CbrgS\&q=85\&s=37b1b615c9fb00a3e8df2d2771976a12)

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.

> [!NOTE]
>
> 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

> [card]
>
> 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

> [card]
>
> 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

> [!TIP]
>
> Choose [`bq-tab`](https://www.beeq.design/components/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`](https://www.beeq.design/components/breadcrumb) to show where a page sits in a site hierarchy instead.

## Patterns

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

> [card] Onboarding and wizards
>
> Guide users through setup flows where each step depends on the previous one.

> [card] Process overviews
>
> Summarize a task, service, or project flow when readers need the full sequence before they start.

> [card] Progress tracking
>
> Show completed, current, upcoming, blocked, or disabled stages in a process that changes over time.

## Anatomy

![BEEQ Steps component anatomy](https://mintlify.s3.us-west-1.amazonaws.com/beeq/components/images/steps/steps-anatomy-light.svg)

Steps component 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

![Choose one type](https://www.beeq.design/components/images/steps/steps-type-light.svg)
![Choose one type](https://www.beeq.design/components/images/steps/steps-type-dark.svg)

## Choose one type

Use one steps type per page. Mixing dots, numbers, and icons in the same view makes the process harder to follow.

![Show current status](https://www.beeq.design/components/images/steps/steps-status-light.svg)
![Show current status](https://www.beeq.design/components/images/steps/steps-status-dark.svg)

## Show current status

The current step must be distinguishable from completed and remaining steps. Don't use color as the only signal; combine it with status, text, and icon changes.

![Keep flows manageable](https://www.beeq.design/components/images/steps/steps-manageable-flow-light.svg)
![Keep flows manageable](https://www.beeq.design/components/images/steps/steps-manageable-flow-dark.svg)

## Keep flows manageable

Keep processes concise. Long forms are easier to complete when the step count stays focused and predictable.

![Pick the right orientation](https://www.beeq.design/components/images/steps/steps-orientation-light.svg)
![Pick the right orientation](https://www.beeq.design/components/images/steps/steps-orientation-dark.svg)

## Pick the right orientation

Use horizontal steps for left-to-right progression. Use vertical steps when horizontal space is limited or when descriptions need more room.

### 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.

> [!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.

```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-steps type="numeric">
  <bq-step-item>
    <span aria-label="Step 1" slot="prefix">1</span>
    <span>Account</span>
    <span slot="description">Create your account</span>
  </bq-step-item>
  <bq-step-item>
    <span aria-label="Step 2" slot="prefix">2</span>
    <span>Profile</span>
    <span slot="description">Complete your profile details</span>
  </bq-step-item>
  <bq-step-item>
    <span aria-label="Step 3" slot="prefix">3</span>
    <span>Review and Submit</span>
    <span slot="description">Review your details and submit</span>
  </bq-step-item>
</bq-steps>
```

```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqStepItem, BqSteps } from "@beeq/react";

<BqSteps type="numeric">
  <BqStepItem>
    <span aria-label="Step 1" slot="prefix">1</span>
    <span>Account</span>
    <span slot="description">Create your account</span>
  </BqStepItem>
  <BqStepItem>
    <span aria-label="Step 2" slot="prefix">2</span>
    <span>Profile</span>
    <span slot="description">Complete your profile details</span>
  </BqStepItem>
  <BqStepItem>
    <span aria-label="Step 3" slot="prefix">3</span>
    <span>Review and Submit</span>
    <span slot="description">Review your details and submit</span>
  </BqStepItem>
</BqSteps>
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqStepItem, BqSteps } from "@beeq/angular/standalone";

@Component({
  standalone: true,
  imports: [BqStepItem, BqSteps],
  template: `
    <bq-steps type="numeric">
      <bq-step-item>
        <span aria-label="Step 1" slot="prefix">1</span>
        <span>Account</span>
        <span slot="description">Create your account</span>
      </bq-step-item>
      <bq-step-item>
        <span aria-label="Step 2" slot="prefix">2</span>
        <span>Profile</span>
        <span slot="description">Complete your profile details</span>
      </bq-step-item>
      <bq-step-item>
        <span aria-label="Step 3" slot="prefix">3</span>
        <span>Review and Submit</span>
        <span slot="description">Review your details and submit</span>
      </bq-step-item>
    </bq-steps>
  `
})
export class NumericStepsComponent {}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqStepItem, BqSteps } from "@beeq/vue";
</script>

<template>
  <bq-steps type="numeric">
    <bq-step-item>
      <span aria-label="Step 1" slot="prefix">1</span>
      <span>Account</span>
      <span slot="description">Create your account</span>
    </bq-step-item>
    <bq-step-item>
      <span aria-label="Step 2" slot="prefix">2</span>
      <span>Profile</span>
      <span slot="description">Complete your profile details</span>
    </bq-step-item>
    <bq-step-item>
      <span aria-label="Step 3" slot="prefix">3</span>
      <span>Review and Submit</span>
      <span slot="description">Review your details and submit</span>
    </bq-step-item>
  </bq-steps>
</template>
```

### Dot

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

```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-steps type="dot">
  <bq-step-item>
    <bq-icon aria-hidden="true" slot="prefix" name="check-circle"></bq-icon>
    <span>Plan</span>
    <span slot="description">Scope approved</span>
  </bq-step-item>
  <bq-step-item>
    <bq-icon aria-hidden="true" slot="prefix" name="circle"></bq-icon>
    <span>Build</span>
    <span slot="description">Work in progress</span>
  </bq-step-item>
  <bq-step-item>
    <bq-icon aria-hidden="true" slot="prefix" name="circle"></bq-icon>
    <span>Launch</span>
    <span slot="description">Ready next</span>
  </bq-step-item>
</bq-steps>
```

```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon, BqStepItem, BqSteps } from "@beeq/react";

<BqSteps type="dot">
  <BqStepItem>
    <BqIcon aria-hidden="true" slot="prefix" name="check-circle" />
    <span>Plan</span>
    <span slot="description">Scope approved</span>
  </BqStepItem>
  <BqStepItem>
    <BqIcon aria-hidden="true" slot="prefix" name="circle" />
    <span>Build</span>
    <span slot="description">Work in progress</span>
  </BqStepItem>
  <BqStepItem>
    <BqIcon aria-hidden="true" slot="prefix" name="circle" />
    <span>Launch</span>
    <span slot="description">Ready next</span>
  </BqStepItem>
</BqSteps>
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqIcon, BqStepItem, BqSteps } from "@beeq/angular/standalone";

@Component({
  standalone: true,
  imports: [BqIcon, BqStepItem, BqSteps],
  template: `
    <bq-steps type="dot">
      <bq-step-item>
        <bq-icon aria-hidden="true" slot="prefix" name="check-circle"></bq-icon>
        <span>Plan</span>
        <span slot="description">Scope approved</span>
      </bq-step-item>
      <bq-step-item>
        <bq-icon aria-hidden="true" slot="prefix" name="circle"></bq-icon>
        <span>Build</span>
        <span slot="description">Work in progress</span>
      </bq-step-item>
      <bq-step-item>
        <bq-icon aria-hidden="true" slot="prefix" name="circle"></bq-icon>
        <span>Launch</span>
        <span slot="description">Ready next</span>
      </bq-step-item>
    </bq-steps>
  `
})
export class DotStepsComponent {}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqIcon, BqStepItem, BqSteps } from "@beeq/vue";
</script>

<template>
  <BqSteps type="dot">
    <BqStepItem>
      <BqIcon aria-hidden="true" slot="prefix" name="check-circle" />
      <span>Plan</span>
      <span slot="description">Scope approved</span>
    </BqStepItem>
    <BqStepItem>
      <BqIcon aria-hidden="true" slot="prefix" name="circle" />
      <span>Build</span>
      <span slot="description">Work in progress</span>
    </BqStepItem>
    <BqStepItem>
      <BqIcon aria-hidden="true" slot="prefix" name="circle" />
      <span>Launch</span>
      <span slot="description">Ready next</span>
    </BqStepItem>
  </BqSteps>
</template>
```

### Icon

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

```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-steps type="icon">
  <bq-step-item>
    <bq-icon aria-hidden="true" slot="prefix" name="user"></bq-icon>
    <span>Account</span>
    <span slot="description">Account created</span>
  </bq-step-item>
  <bq-step-item>
    <bq-icon aria-hidden="true" slot="prefix" name="gear"></bq-icon>
    <span>Settings</span>
    <span slot="description">Choose preferences</span>
  </bq-step-item>
  <bq-step-item>
    <bq-icon aria-hidden="true" slot="prefix" name="check-circle"></bq-icon>
    <span>Confirm</span>
    <span slot="description">Review and submit</span>
  </bq-step-item>
</bq-steps>
```

```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqIcon, BqStepItem, BqSteps } from "@beeq/react";

<BqSteps type="icon">
  <BqStepItem>
    <BqIcon aria-hidden="true" slot="prefix" name="user" />
    <span>Account</span>
    <span slot="description">Account created</span>
  </BqStepItem>
  <BqStepItem>
    <BqIcon aria-hidden="true" slot="prefix" name="gear" />
    <span>Settings</span>
    <span slot="description">Choose preferences</span>
  </BqStepItem>
  <BqStepItem>
    <BqIcon aria-hidden="true" slot="prefix" name="check-circle" />
    <span>Confirm</span>
    <span slot="description">Review and submit</span>
  </BqStepItem>
</BqSteps>
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqIcon, BqStepItem, BqSteps } from "@beeq/angular/standalone";

@Component({
  standalone: true,
  imports: [BqIcon, BqStepItem, BqSteps],
  template: `
    <bq-steps type="icon">
      <bq-step-item>
        <bq-icon aria-hidden="true" slot="prefix" name="user"></bq-icon>
        <span>Account</span>
        <span slot="description">Account created</span>
      </bq-step-item>
      <bq-step-item>
        <bq-icon aria-hidden="true" slot="prefix" name="gear"></bq-icon>
        <span>Settings</span>
        <span slot="description">Choose preferences</span>
      </bq-step-item>
      <bq-step-item>
        <bq-icon aria-hidden="true" slot="prefix" name="check-circle"></bq-icon>
        <span>Confirm</span>
        <span slot="description">Review and submit</span>
      </bq-step-item>
    </bq-steps>
  `
})
export class IconStepsComponent {}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqIcon, BqStepItem, BqSteps } from "@beeq/vue";
</script>

<template>
  <BqSteps type="icon">
    <BqStepItem>
      <BqIcon aria-hidden="true" slot="prefix" name="user" />
      <span>Account</span>
      <span slot="description">Account created</span>
    </BqStepItem>
    <BqStepItem>
      <BqIcon aria-hidden="true" slot="prefix" name="gear" />
      <span>Settings</span>
      <span slot="description">Choose preferences</span>
    </BqStepItem>
    <BqStepItem>
      <BqIcon aria-hidden="true" slot="prefix" name="check-circle" />
      <span>Confirm</span>
      <span slot="description">Review and submit</span>
    </BqStepItem>
  </BqSteps>
</template>
```

## 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`.

> [!TIP]
>
> 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. |

```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-steps type="numeric">
  <bq-step-item status="completed">
    <span aria-label="Step 1" slot="prefix">1</span>
    <span>Completed</span>
    <span slot="description">Completed</span>
  </bq-step-item>
  <bq-step-item status="current">
    <span aria-label="Step 2" slot="prefix">2</span>
    <span>Current</span>
    <span slot="description">Current step</span>
  </bq-step-item>
  <bq-step-item status="error">
    <span aria-label="Step 3" slot="prefix">3</span>
    <span>Error</span>
    <span slot="description">You need to address an issue</span>
  </bq-step-item>
  <bq-step-item status="disabled">
    <span aria-label="Step 4" slot="prefix">4</span>
    <span>Disabled</span>
    <span slot="description">Complete previous steps first</span>
  </bq-step-item>
</bq-steps>
```

```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqStepItem, BqSteps } from "@beeq/react";

<BqSteps type="numeric">
  <BqStepItem status="completed">
    <span aria-label="Step 1" slot="prefix">1</span>
    <span>Completed</span>
    <span slot="description">Completed</span>
  </BqStepItem>
  <BqStepItem status="current">
    <span aria-label="Step 2" slot="prefix">2</span>
    <span>Current</span>
    <span slot="description">Current step</span>
  </BqStepItem>
  <BqStepItem status="error">
    <span aria-label="Step 3" slot="prefix">3</span>
    <span>Error</span>
    <span slot="description">You need to address an issue</span>
  </BqStepItem>
  <BqStepItem status="disabled">
    <span aria-label="Step 4" slot="prefix">4</span>
    <span>Disabled</span>
    <span slot="description">Complete previous steps first</span>
  </BqStepItem>
</BqSteps>
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqStepItem, BqSteps } from "@beeq/angular/standalone";

@Component({
  standalone: true,
  imports: [BqStepItem, BqSteps],
  template: `
    <bq-steps type="numeric">
      <bq-step-item status="completed">
        <span aria-label="Step 1" slot="prefix">1</span>
        <span>Completed</span>
        <span slot="description">Completed</span>
      </bq-step-item>
      <bq-step-item status="current">
        <span aria-label="Step 2" slot="prefix">2</span>
        <span>Current</span>
        <span slot="description">Current step</span>
      </bq-step-item>
      <bq-step-item status="error">
        <span aria-label="Step 3" slot="prefix">3</span>
        <span>Error</span>
        <span slot="description">You need to address an issue</span>
      </bq-step-item>
      <bq-step-item status="disabled">
        <span aria-label="Step 4" slot="prefix">4</span>
        <span>Disabled</span>
        <span slot="description">Complete previous steps first</span>
      </bq-step-item>
    </bq-steps>
  `
})
export class StatusStepsComponent {}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqStepItem, BqSteps } from "@beeq/vue";
</script>

<template>
  <BqSteps type="numeric">
    <BqStepItem status="completed">
      <span aria-label="Step 1" slot="prefix">1</span>
      <span>Completed</span>
      <span slot="description">Completed</span>
    </BqStepItem>
    <BqStepItem status="current">
      <span aria-label="Step 2" slot="prefix">2</span>
      <span>Current</span>
      <span slot="description">Current step</span>
    </BqStepItem>
    <BqStepItem status="error">
      <span aria-label="Step 3" slot="prefix">3</span>
      <span>Error</span>
      <span slot="description">You need to address an issue</span>
    </BqStepItem>
    <BqStepItem status="disabled">
      <span aria-label="Step 4" slot="prefix">4</span>
      <span>Disabled</span>
      <span slot="description">Complete previous steps first</span>
    </BqStepItem>
  </BqSteps>
</template>
```

## 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.

```css styles.css icon="css" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
body {
  display: flex;
  padding: var(--bq-spacing-m);
}

.container {
  display: flex;
  flex-direction: column;
  flex-grow: 1;
}
```

```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<div class="container">
  <bq-steps orientation="vertical" type="numeric">
    <bq-step-item status="completed">
      <span aria-label="Step 1" slot="prefix">1</span>
      <span>Request</span>
    </bq-step-item>
    <bq-step-item status="current">
      <span aria-label="Step 2" slot="prefix">2</span>
      <span>Review</span>
    </bq-step-item>
    <bq-step-item>
      <span aria-label="Step 3" slot="prefix">3</span>
      <span>Decision</span>
    </bq-step-item>
  </bq-steps>
</div>
```

```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqStepItem, BqSteps } from "@beeq/react";
import "./styles.css";

<div className="container">
  <BqSteps orientation="vertical" type="numeric">
    <BqStepItem status="completed">
      <span aria-label="Step 1" slot="prefix">1</span>
      <span>Request</span>
    </BqStepItem>
    <BqStepItem status="current">
      <span aria-label="Step 2" slot="prefix">2</span>
      <span>Review</span>
    </BqStepItem>
    <BqStepItem>
      <span aria-label="Step 3" slot="prefix">3</span>
      <span>Decision</span>
    </BqStepItem>
  </BqSteps>
</div>
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqStepItem, BqSteps } from "@beeq/angular/standalone";

@Component({
  standalone: true,
  imports: [BqStepItem, BqSteps],
  template: `
    <div class="container">
      <bq-steps orientation="vertical" type="numeric">
        <bq-step-item status="completed">
          <span aria-label="Step 1" slot="prefix">1</span>
          <span>Request</span>
        </bq-step-item>
        <bq-step-item status="current">
          <span aria-label="Step 2" slot="prefix">2</span>
          <span>Review</span>
        </bq-step-item>
        <bq-step-item>
          <span aria-label="Step 3" slot="prefix">3</span>
          <span>Decision</span>
        </bq-step-item>
      </bq-steps>
    </div>
  `,
  styles: [`
    body {
      display: flex;
      padding: var(--bq-spacing-m);
    }

    .container {
      display: flex;
      flex-direction: column;
      flex-grow: 1;
    }
  `],
})
export class VerticalStepsComponent {}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqStepItem, BqSteps } from "@beeq/vue";
</script>

<template>
  <div class="container">
    <BqSteps orientation="vertical" type="numeric">
      <BqStepItem status="completed">
        <span aria-label="Step 1" slot="prefix">1</span>
        <span>Request</span>
      </BqStepItem>
      <BqStepItem status="current">
        <span aria-label="Step 2" slot="prefix">2</span>
        <span>Review</span>
      </BqStepItem>
      <BqStepItem>
        <span aria-label="Step 3" slot="prefix">3</span>
        <span>Decision</span>
      </BqStepItem>
    </BqSteps>
  </div>
</template>

<style>
  body {
    display: flex;
    padding: var(--bq-spacing-m);
  }

  .container {
    display: flex;
    flex-direction: column;
    flex-grow: 1;
  }
</style>
```

> [!TIP]
>
> 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.

```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-steps divider-color="stroke--brand" size="small" type="numeric">
  <bq-step-item status="completed">
    <span aria-label="Step 1" slot="prefix">1</span>
    <span>Account</span>
    <span slot="description">Completed</span>
  </bq-step-item>
  <bq-step-item status="current">
    <span aria-label="Step 2" slot="prefix">2</span>
    <span>Preferences</span>
    <span slot="description">Current step</span>
  </bq-step-item>
  <bq-step-item>
    <span aria-label="Step 3" slot="prefix">3</span>
    <span>Finish</span>
    <span slot="description">Next step</span>
  </bq-step-item>
</bq-steps>
```

```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqStepItem, BqSteps } from "@beeq/react";

<BqSteps dividerColor="stroke--brand" size="small" type="numeric">
  <BqStepItem status="completed">
    <span aria-label="Step 1" slot="prefix">1</span>
    <span>Account</span>
    <span slot="description">Completed</span>
  </BqStepItem>
  <BqStepItem status="current">
    <span aria-label="Step 2" slot="prefix">2</span>
    <span>Preferences</span>
    <span slot="description">Current step</span>
  </BqStepItem>
  <BqStepItem>
    <span aria-label="Step 3" slot="prefix">3</span>
    <span>Finish</span>
    <span slot="description">Next step</span>
  </BqStepItem>
</BqSteps>
```

```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqStepItem, BqSteps } from "@beeq/angular/standalone";

@Component({
  standalone: true,
  imports: [BqStepItem, BqSteps],
  template: `
    <bq-steps divider-color="stroke--brand" size="small" type="numeric">
      <bq-step-item status="completed">
        <span aria-label="Step 1" slot="prefix">1</span>
        <span>Account</span>
        <span slot="description">Completed</span>
      </bq-step-item>
      <bq-step-item status="current">
        <span aria-label="Step 2" slot="prefix">2</span>
        <span>Preferences</span>
        <span slot="description">Current step</span>
      </bq-step-item>
      <bq-step-item>
        <span aria-label="Step 3" slot="prefix">3</span>
        <span>Finish</span>
        <span slot="description">Next step</span>
      </bq-step-item>
    </bq-steps>
  `
})
export class SmallStepsComponent {}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqStepItem, BqSteps } from "@beeq/vue";
</script>

<template>
  <BqSteps dividerColor="stroke--brand" size="small" type="numeric">
    <BqStepItem status="completed">
      <span aria-label="Step 1" slot="prefix">1</span>
      <span>Account</span>
      <span slot="description">Completed</span>
    </BqStepItem>
    <BqStepItem status="current">
      <span aria-label="Step 2" slot="prefix">2</span>
      <span>Preferences</span>
      <span slot="description">Current step</span>
    </BqStepItem>
    <BqStepItem>
      <span aria-label="Step 3" slot="prefix">3</span>
      <span>Finish</span>
      <span slot="description">Next step</span>
    </BqStepItem>
  </BqSteps>
</template>
```

## Best practices

> [card]
>
> Do
>
> Use one steps component per page so the process stays clear and cohesive.

> [card]
>
> Don't
>
> Avoid multiple Steps components in the same view because they can compete for attention and disrupt the flow.

> [card]
>
> Do
>
> Write labels that describe the task or destination for each step.

> [card]
>
> Don't
>
> Avoid labels that only repeat the status, such as current or completed.

> [card]
>
> Do
>
> Confirm progress with status, text, and icon changes after a step is completed.

> [card]
>
> Don't
>
> Do not rely on color alone to communicate the state of a step.

> [card]
>
> Do
>
> Keep the number of steps manageable so users feel the process is achievable.

> [card]
>
> Don't
>
> Avoid 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>` |

> [!NOTE]
>
> * 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--gap` | Gap between steps | `var(--bq-spacing-m)` |

#### `bq-step-item`

**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)` |

> [!TIP]
>
> Learn more about [styling with shadow parts](https://www.beeq.design/guides/styles.md) and [CSS custom properties](https://www.beeq.design/theming/global-css-variables.md).

## Resources

> [card] [Interactive playground](https://storybook.beeq.design/?path=/story/components-steps--default)
>
> Explore Steps variants and states in Storybook

> [card] [Source code](https://github.com/Endava/BEEQ/tree/main/packages/beeq/src/components/steps)
>
> View the component source on GitHub


## Related topics

- [Time Picker](https://www.beeq.design/components/time-picker.md)
- [Custom Theme](https://www.beeq.design/theming/custom-theme.md)
- [Slider](https://www.beeq.design/components/slider.md)
- [Global CSS Variables](https://www.beeq.design/theming/global-css-variables.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.