`<bmx-stepper>`

A task in steps - a wizard, a checkout, an onboarding - with a step list that shows where the reader is, what is done and what needs attention, and Back and Next buttons. Write the steps:

8 properties · 3 events · 9 methods · 11 parts

Example

Next checks the fields in the step first: try it empty.

Postcode

Message

Finish completes the last step and fires bmxComplete.

Steps after the first wait until it is completed. The optional step can be passed over.

Down the side, any step in any order

The first step is already done.

A step can be shown as needing attention.

Choose any step from the list.

Not available on this plan.

Show markup

<div class="row" style="display: block">
  <bmx-stepper id="ex-stepper" label="Checkout" style="max-inline-size: 48rem">
    <bmx-step label="Account" description="Who you are">
      <p style="margin: 0 0 8px"><label for="ex-st-email">Email</label><br /><input id="ex-st-email" type="email" required autocomplete="email" /></p>
      <p class="note" style="margin: 0">Next checks the fields in the step first: try it empty.</p>
    </bmx-step>
    <bmx-step label="Delivery" description="Where it goes">
      <p style="margin: 0 0 8px"><label for="ex-st-post">Postcode</label><br /><input id="ex-st-post" required /></p>
    </bmx-step>
    <bmx-step label="Gift message" optional>
      <p style="margin: 0"><label for="ex-st-gift">Message</label><br /><textarea id="ex-st-gift" rows="2"></textarea></p>
    </bmx-step>
    <bmx-step label="Review">
      <p style="margin: 0">Finish completes the last step and fires <code>bmxComplete</code>.</p>
    </bmx-step>
  </bmx-stepper>
</div>
<p class="note" id="ex-stepper-out" role="status">Steps after the first wait until it is completed. The optional step can be passed over.</p>

<h3>Down the side, any step in any order</h3>

<div class="row" style="display: block">
  <bmx-stepper orientation="vertical" linear="false" label="Setting up a project" style="max-inline-size: 48rem">
    <bmx-step label="Create the project" state="done">The first step is already done.</bmx-step>
    <bmx-step label="Connect a repository" state="error" error-text="The token has expired">A step can be shown as needing attention.</bmx-step>
    <bmx-step label="Invite people">Choose any step from the list.</bmx-step>
    <bmx-step label="Billing" disabled>Not available on this plan.</bmx-step>
  </bmx-stepper>
</div>

<script type="module">
  await customElements.whenDefined('bmx-stepper');
  const stepper = document.getElementById('ex-stepper');
  const out = document.getElementById('ex-stepper-out');
  stepper.beforeChange = ({ fromValue }) => {
    if (fromValue === 'Delivery' && !/^[A-Za-z0-9 ]{3,10}$/.test(document.getElementById('ex-st-post').value)) return 'That postcode does not look right.';
  };
  stepper.addEventListener('bmxStepChanged', e => (out.textContent = `Now on ${e.detail.toValue}.`));
  stepper.addEventListener('bmxComplete', e => (out.textContent = `Done: ${e.detail.completed.join(', ')}.`));
</script>

<bmx-stepper>
  <bmx-step label="Account">…</bmx-step>
  <bmx-step label="Shipping" optional>…</bmx-step>
  <bmx-step label="Payment">…</bmx-step>
</bmx-stepper>

Linear by default: a step can be reached once every required step before it is completed, and Next completes a step only when the forms and fields in it are valid (bmx-form, a <form>, or loose fields), the page's beforeChange agrees and bmxStepChange is not cancelled. linear="false" lets the reader go to any step. Vertical puts the step list beside the content. Narrow, the list becomes "Step 2 of 5" with a progress bar.

The step list is a navigation landmark holding an ordered list of buttons: the current step has aria-current="step", and each button's name says whether its step is completed, needs attention or cannot be reached yet. The arrow keys, Home and End move along it. The content is a group named by its step, focused when Back or Next moves to it.

Properties

Property	Attribute	Type	Default	Description
`beforeChange`	property only	`BmxStepGuard`	—	The page's own check before a step is left forward, or finished.
`hideControls`	`hide-controls`	`boolean`	`false`	Leave out the Back and Next buttons, for a page that moves the steps itself.
`label`	`label`	`string`	—	The step list's accessible name. Default: "Progress".
`linear`	`linear`	`boolean`	`true`	Steps in order: a step can be reached once every required step before it is completed. `false` lets any step be chosen.
`noValidate`	`no-validate`	`boolean`	`false`	Do not check the forms and fields in a step before leaving it forward.
`orientation`	`orientation`	`'horizontal' \| 'vertical'`	`'horizontal'`	The step list across the top (`horizontal`) or down the side (`vertical`).
`strings`	`strings`	`Partial<BmxStepperStrings> \| string`	—	Words to show instead of the English ones, as an object or JSON.
`value`	`value`	`string`	—	The current step, by value. Mutable: moving updates it.

Events

Event	Detail	Description
`bmxComplete`	`BmxStepperCompleteDetail`	Fired when Finish completes the last step.
`bmxStepChange`	`BmxStepChangeDetail`	Fired before the current step changes. Cancel it to stay.
`bmxStepChanged`	`BmxStepChangeDetail`	Fired after the current step has changed.

Methods

Method	Signature	Description
`finish`	`finish() => Promise<boolean>`	Completes the last step, after its checks, and fires `bmxComplete`. Resolves whether it finished.
`getCompleted`	`getCompleted() => Promise<string[]>`	The values of the completed steps, in order.
`goTo`	`goTo(step: string \| number) => Promise<boolean>`	Moves to a step by value or position, if it can be reached. Resolves whether it moved.
`next`	`next() => Promise<boolean>`	Moves to the next step, after its checks. Resolves whether it moved.
`previous`	`previous() => Promise<boolean>`	Moves to the step before. Resolves whether it moved.
`reset`	`reset() => Promise<void>`	Back to the first step, with nothing completed.
`setCompleted`	`setCompleted(step: string, completed?: boolean) => Promise<void>`	Marks a step as completed (true) or not (false).
`setError`	`setError(step: string, message: string \| null) => Promise<void>`	Shows a step as needing attention, with a message; null clears it.
`setFocus`	`setFocus(options?: FocusOptions) => Promise<void>`	Focuses the current step in the step list.

Slots

Slot	Description
`(default)`	`bmx-step` elements.

CSS shadow parts

Part	Description
`actions`	The row of Back and Next.
`back`	The Back button.
`compact`	The "Step 2 of 5" heading shown when narrow.
`content`	The current step's content.
`description`	A step's description.
`label`	A step's label.
`marker`	The circle with the step's number, tick or warning.
`message`	Why a step could not be left.
`next`	The Next (or Finish) button.
`step`	One step's button; also `step-current`, `step-done`, `step-error`, `step-disabled` by state.
`steps`	The step list.

CSS custom properties

Property	Description
`--bmx-stepper-gap`	Space between the step list and the content.
`--bmx-stepper-line`	The colour of the line joining the steps.
`--bmx-stepper-line-done`	The colour of the line after a completed step.
`--bmx-stepper-marker-size`	The diameter of a step's numbered circle.
`--bmx-stepper-side-width`	The width of the step list in the vertical layout.