> ## 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. export const CodeLivePreview = ({code, children, height, removePadding = false, mode = 'shadow'}) => { const previewRef = useRef(null); const BEEQ_ESM_URL = 'https://esm.sh/@beeq/core/dist/beeq/beeq.esm.js'; const BEEQ_CSS_URL = 'https://esm.sh/@beeq/core/dist/beeq/beeq.css'; const BEEQ_ICONS_URL = 'https://esm.sh/@beeq/core/dist/beeq/svg'; const ensureParentBeeqRuntime = () => { if (document.querySelector('script[data-beeq-parent-runtime]')) return; const script = document.createElement('script'); script.type = 'module'; script.src = BEEQ_ESM_URL; script.dataset.beeqParentRuntime = BEEQ_ICONS_URL; document.head.appendChild(script); }; const executeSnippetScripts = (root, runtimeWindow, previewRootArg, skipAttr) => { root.querySelectorAll('script').forEach(oldScript => { if (skipAttr && oldScript.hasAttribute(skipAttr)) return; if (oldScript.src) { const newScript = runtimeWindow.document.createElement('script'); newScript.src = oldScript.src; oldScript.replaceWith(newScript); return; } runtimeWindow.Function('previewRoot', oldScript.textContent || '')(previewRootArg); oldScript.remove(); }); }; const syncIframeMode = iframeDoc => { const root = document.documentElement; const explicitMode = root.getAttribute('bq-mode'); const isDark = root.classList.contains('dark'); const resolvedMode = explicitMode || (isDark ? 'dark' : 'light'); iframeDoc.documentElement.setAttribute('bq-mode', resolvedMode); iframeDoc.body.setAttribute('bq-mode', resolvedMode); }; useEffect(() => { if (mode === 'shadow') ensureParentBeeqRuntime(); }, [mode]); useEffect(() => { const container = previewRef.current; if (!container) return; if (removePadding) container.style.padding = '0'; container.innerHTML = ''; if (mode === 'iframe') { const iframe = document.createElement('iframe'); iframe.className = 'preview-iframe'; iframe.style.width = '100%'; iframe.style.border = '0'; iframe.style.display = 'block'; iframe.style.minHeight = height ?? '0px'; iframe.setAttribute('title', 'Live code preview'); iframe.setAttribute('loading', 'lazy'); iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin'); container.appendChild(iframe); const iframeDoc = iframe.contentDocument; const iframeWin = iframe.contentWindow; if (!iframeDoc || !iframeWin) return; iframeDoc.open(); iframeDoc.write(['', '', '', ' ', ' ', ' ', ` `, ` `, '', '', code, '', ''].join('\n')); iframeDoc.close(); syncIframeMode(iframeDoc); const modeObserver = new MutationObserver(() => syncIframeMode(iframeDoc)); modeObserver.observe(document.documentElement, { attributes: true, attributeFilter: ['class', 'bq-mode'] }); executeSnippetScripts(iframeDoc, iframeWin, iframeDoc, 'data-beeq-iframe-runtime'); return () => modeObserver.disconnect(); } const shadowRoot = container.shadowRoot ?? container.attachShadow({ mode: 'open' }); if (!shadowRoot.adoptedStyleSheets.length) { const fixSheet = new CSSStyleSheet(); fixSheet.replaceSync(` bq-dropdown::part(panel), bq-panel::part(panel), bq-select::part(panel), bq-date-picker::part(panel) { z-index: 9999; } bq-tooltip::part(panel) { position: absolute; } `); shadowRoot.adoptedStyleSheets = [fixSheet]; } shadowRoot.innerHTML = [``, code].join(''); executeSnippetScripts(shadowRoot, window, shadowRoot); return undefined; }, [code, mode, height]); return
{}
{} {children &&
{children}
}
; }; export const CardTile = ({title, href, imageLightSrc, imageDarkSrc, children, enableImgZoom}) => { if (!href) { return
{imageLightSrc && {title}} {imageDarkSrc && {title}} {title &&

{title}

}
{children}
; } return {imageLightSrc && {title}} {imageDarkSrc && {title}} {title &&

{title}

}
{children}
; }; BEEQ Steps component overview BEEQ 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. 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 Split long forms into clear stages so users can see what is complete, where they are, and what remains. Guide users through setup flows where each step depends on the previous one. Summarize a task, service, or project flow when readers need the full sequence before they start. Show completed, current, upcoming, blocked, or disabled stages in a process that changes over time. ## Anatomy BEEQ Steps component anatomy BEEQ 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 Use one steps type per page. Mixing dots, numbers, and icons in the same view makes the process harder to follow. Distinguish the current step from completed and remaining steps. Use status, text, and icon changes so color is not the only signal. Keep processes concise. Long forms are easier to complete when the step count stays focused and predictable. 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`. 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. body { padding: var(--bq-spacing-m); } /* Optional: Set a fixed width for numeric prefixes */ span[slot="prefix"] { min-inline-size: var(--bq-step-item--prefix-number-size, var(--bq-spacing-xl)); } 1 Account Create your account 2 Profile Complete your profile details 3 Review and Submit Review your details and submit `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} 1 Account Create your account 2 Profile Complete your profile details 3 Review and Submit Review your details and submit ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqStepItem, BqSteps } from "@beeq/react"; 1 Account Create your account 2 Profile Complete your profile details 3 Review and Submit Review your details and submit ``` ```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: ` 1 Account Create your account 2 Profile Complete your profile details 3 Review and Submit Review your details and submit ` }) export class NumericStepsComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Dot Use `type="dot"` for a minimal progress indicator when the sequence is clear and the step labels carry most of the meaning. body { padding: var(--bq-spacing-m); } Plan Scope approved Build Work in progress Launch Ready next `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Plan Scope approved Build Work in progress Launch Ready next ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqStepItem, BqSteps } from "@beeq/react"; ``` ```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: ` Plan Scope approved Build Work in progress Launch Ready next ` }) export class DotStepsComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Icon Use `type="icon"` when each step benefits from a recognizable symbol. Icons should support the label, not replace it. body { padding: var(--bq-spacing-m); } Account Account created Settings Choose preferences Confirm Review and submit `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} Account Account created Settings Choose preferences Confirm Review and submit ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqIcon, BqStepItem, BqSteps } from "@beeq/react"; ``` ```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: ` Account Account created Settings Choose preferences Confirm Review and submit ` }) export class IconStepsComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## 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. | body { padding: var(--bq-spacing-m); } span[slot="prefix"] { min-inline-size: var(--bq-step-item--prefix-number-size, var(--bq-spacing-xl)); } 1 Completed Completed 2 Current Current step 3 Error You need to address an issue 4 Disabled Complete previous steps first `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} 1 Completed Completed 2 Current Current step 3 Error You need to address an issue 4 Disabled Complete previous steps first ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqStepItem, BqSteps } from "@beeq/react"; 1 Completed Completed 2 Current Current step 3 Error You need to address an issue 4 Disabled Complete previous steps first ``` ```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: ` 1 Completed Completed 2 Current Current step 3 Error You need to address an issue 4 Disabled Complete previous steps first ` }) export class StatusStepsComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Options ### Orientation Use `orientation="vertical"` when the process should unfold from top to bottom or when labels and descriptions need more room. body { display: flex; padding: var(--bq-spacing-m); } .container { display: flex; flex-direction: column; flex-grow: 1; } span[slot="prefix"] { min-inline-size: var(--bq-step-item--prefix-number-size, var(--bq-spacing-xl)); }
1 Request 2 Review 3 Decision
`} > ```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"}}
1 Request 2 Review 3 Decision
``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqStepItem, BqSteps } from "@beeq/react"; import "./styles.css";
1 Request 2 Review 3 Decision
``` ```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: `
1 Request 2 Review 3 Decision
`, 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"}} ``` 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. body { padding: var(--bq-spacing-m); } span[slot="prefix"] { min-inline-size: var(--bq-spacing-l); } 1 Account Completed 2 Preferences Current step 3 Finish Next step `} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} 1 Account Completed 2 Preferences Current step 3 Finish Next step ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqStepItem, BqSteps } from "@beeq/react"; 1 Account Completed 2 Preferences Current step 3 Finish Next step ``` ```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: ` 1 Account Completed 2 Preferences Current step 3 Finish Next step ` }) export class SmallStepsComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Best practices Do Use one steps component per page so the process stays clear and cohesive. Don't Avoid multiple steppers in the same view because they can compete for attention and disrupt the flow. Do Write labels that describe the task or destination for each step. Don't Avoid labels that only repeat the status, such as current or completed. Do Confirm progress with status, text, and icon changes after a step is completed. Don't Do not rely on color alone to communicate the state of a step. Do Keep the number of steps manageable so users feel the process is achievable. 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. * **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` | | `bqFocus` | Fires when a step item receives focus | `CustomEvent` | | `bqBlur` | Fires when a step item loses focus | `CustomEvent` | * 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` | ### 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](/guides/styles) and [CSS custom properties](/theming/global-css-variables). ## Resources Explore Steps variants and states in Storybook View the component source on GitHub