Navigation

Wizard

<forma-wizard>

Step-by-step workflow shell with current-step state, progress, validation hooks, resume, and mobile reduction.

Authoring tag
<forma-wizard>
Category
Navigation
Behavior owner
Limen / Ordo
Canonical source
patterns/wizard.html

Purpose

The wizard is a bordered shell for a task split into ordered steps: a header with the step position, title and a native progress bar; a step rail marking complete and current steps; a body for the current step's fields; and a footer of actions. Forma renders whatever state it is given. Limen and Ordo own the workflow: which steps exist (including branching), whether the user may advance, validation before advance, save and exit, resume, and whether earlier steps can be revisited. On phones the rail reduces to the current step only.

Use when

  • A task has several dependent stages that must be completed in order, such as configure, review, validate, publish.
  • Users benefit from knowing how many steps remain and which one they are on.
  • The workflow can be saved and resumed, or must validate each stage before continuing.

Avoid when

  • The steps are independent views the user can visit in any order: use Tabs.
  • It is a short form that fits on one page: use a single form with Validation summary.
  • Progress through a survey without step navigation: use Survey progress.
  • A static list of instructions: use Steps.

Behavior to know

  • Step state is written with data-state="complete" and data-state="current" plus aria-current="step" on the current item.
  • Position is stated three ways: "Step 2 of 4" text, the progress bar and the rail.
  • The rail is a four-column grid; below 40rem only the current step is shown, labelled Current step.
  • Actions sit at opposite ends of the footer and wrap on narrow screens.

Basic example

The smallest correct markup: the canonical pattern from patterns/wizard.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal wizard

Rendered from the canonical pattern file.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Step 2 of 4

Review details

2 of 4
  1. 1Details
  2. 2Review
  3. 3Validate
  4. 4Publish

Confirm the supplied information before continuing.

HTML · Minimal wizard Raw HTML for HTML · Minimal wizard
<forma-wizard class="forma-component-tag">
<section class="forma-wizard" aria-labelledby="wizard-title">
  <header class="forma-wizard__header">
    <div><span class="forma-wizard__position">Step 2 of 4</span><h3 id="wizard-title">Review details</h3></div>
    <progress value="2" max="4" aria-label="Workflow progress">2 of 4</progress>
  </header>
  <ol class="forma-wizard__steps" aria-label="Workflow steps">
    <li data-state="complete"><span>1</span>Details</li>
    <li data-state="current" aria-current="step"><span>2</span>Review</li>
    <li><span>3</span>Validate</li>
    <li><span>4</span>Publish</li>
  </ol>
  <div class="forma-wizard__body">
    <p>Confirm the supplied information before continuing.</p>
  </div>
  <footer class="forma-wizard__actions">
    <button type="button">Back</button>
    <button type="button">Continue</button>
  </footer>
</section>
</forma-wizard>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Advance blocked by validation

The user pressed Continue on step 1 with a missing field. Ordo refused the transition; the application rendered a focusable validation summary in the body and marked the field invalid. The rail and position are unchanged.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Step 1 of 4

Service details

1 of 4
  1. 1Details
  2. 2Review
  3. 3Validate
  4. 4Publish
HTML · Advance blocked by validation Raw HTML for HTML · Advance blocked by validation
<forma-wizard class="forma-component-tag">
  <section class="forma-wizard" aria-labelledby="wizard-blocked-title">
    <header class="forma-wizard__header">
      <div><span class="forma-wizard__position">Step 1 of 4</span><h3 id="wizard-blocked-title">Service details</h3></div>
      <progress value="1" max="4" aria-label="Workflow progress">1 of 4</progress>
    </header>
    <ol class="forma-wizard__steps" aria-label="Workflow steps">
      <li data-state="current" aria-current="step"><span>1</span>Details</li>
      <li><span>2</span>Review</li>
      <li><span>3</span>Validate</li>
      <li><span>4</span>Publish</li>
    </ol>
    <div class="forma-wizard__body">
      <div class="forma-validation-summary" role="alert" tabindex="-1" aria-labelledby="wizard-blocked-summary-title">
        <div class="forma-validation-summary__icon" aria-hidden="true">!</div>
        <div>
          <h4 class="forma-validation-summary__title" id="wizard-blocked-summary-title">Fix 1 problem to continue</h4>
          <ul class="forma-validation-summary__list"><li><a href="#wizard-blocked-owner">Enter an owning team.</a></li></ul>
        </div>
      </div>
      <div class="forma-field">
        <label class="forma-field__label" for="wizard-blocked-owner">Owning team</label>
        <input id="wizard-blocked-owner" name="wizard-blocked-owner" type="text" required aria-invalid="true">
      </div>
    </div>
    <footer class="forma-wizard__actions">
      <button type="button">Save and exit</button>
      <button type="button">Continue</button>
    </footer>
  </section>
</forma-wizard>

Click or tap the code once to select all of it, then copy.

Scenario

Resumed at the final step

A draft resumed from a saved session. Three steps are complete and Publish is current; the footer offers Back, Save and exit, and the final action.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Step 4 of 4

Publish release 2.8

4 of 4
  1. 1Details
  2. 2Review
  3. 3Validate
  4. 4Publish

Resumed from your draft saved yesterday at 17:42. All checks passed. Publishing makes release 2.8 available to every customer.

HTML · Resumed at the final step Raw HTML for HTML · Resumed at the final step
<forma-wizard class="forma-component-tag">
  <section class="forma-wizard" aria-labelledby="wizard-resume-title">
    <header class="forma-wizard__header">
      <div><span class="forma-wizard__position">Step 4 of 4</span><h3 id="wizard-resume-title">Publish release 2.8</h3></div>
      <progress value="4" max="4" aria-label="Workflow progress">4 of 4</progress>
    </header>
    <ol class="forma-wizard__steps" aria-label="Workflow steps">
      <li data-state="complete"><span>1</span>Details</li>
      <li data-state="complete"><span>2</span>Review</li>
      <li data-state="complete"><span>3</span>Validate</li>
      <li data-state="current" aria-current="step"><span>4</span>Publish</li>
    </ol>
    <div class="forma-wizard__body">
      <p>Resumed from your draft saved yesterday at 17:42. All checks passed. Publishing makes release 2.8 available to every customer.</p>
    </div>
    <footer class="forma-wizard__actions">
      <button type="button">Back</button>
      <button type="button">Save and exit</button>
      <button type="button">Publish release</button>
    </footer>
  </section>
</forma-wizard>

Click or tap the code once to select all of it, then copy.

Mobile

Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.

Mobile example

Wizard on a phone

Below 40rem the header stacks, the rail shows only the current step with a Current step note, and actions wrap if they do not fit.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • The header becomes one column: position and title first, then a full-width progress bar.
  • The step rail hides every item except the current one and appends a "Current step" note, so the rail costs one row.
  • The "Step 3 of 4" text and the progress bar still convey the total, so hiding the other steps does not hide progress.
  • Footer actions are a wrapping flex row with space-between; buttons keep their 44px height and wrap onto a new line when there are three.
HTML · Wizard on a phone Raw HTML for HTML · Wizard on a phone
<forma-wizard class="forma-component-tag">
  <section class="forma-wizard" aria-labelledby="wizard-mobile-title">
    <header class="forma-wizard__header">
      <div><span class="forma-wizard__position">Step 3 of 4</span><h3 id="wizard-mobile-title">Validate configuration</h3></div>
      <progress value="3" max="4" aria-label="Workflow progress">3 of 4</progress>
    </header>
    <ol class="forma-wizard__steps" aria-label="Workflow steps">
      <li data-state="complete"><span>1</span>Details</li>
      <li data-state="complete"><span>2</span>Review</li>
      <li data-state="current" aria-current="step"><span>3</span>Validate</li>
      <li><span>4</span>Publish</li>
    </ol>
    <div class="forma-wizard__body">
      <p>Checking 14 settings against the production policy.</p>
    </div>
    <footer class="forma-wizard__actions">
      <button type="button">Back</button>
      <button type="button">Continue</button>
    </footer>
  </section>
</forma-wizard>

Click or tap the code once to select all of it, then copy.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Static specimen. Its buttons stand for application actions that the consuming application implements; this script-free documentation does not perform them. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

Frames narrower than the selected width show the component at the width available.

API and configuration

Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
aria-labelledbysection.forma-wizardid of the step heading—Names the wizard region by the current step title.
valueprogressnumber—Current step number, supplied by the application.
maxprogressnumber—Total number of steps; update it when branching changes the total.
aria-labelprogress and ol.forma-wizard__stepsstring—Names the progress bar (Workflow progress) and the step list (Workflow steps).
data-statestep licomplete | currentabsent (upcoming)Visual step state written by the application. current also bolds the step and inverts its marker; complete adds a check glyph.
aria-currentcurrent step listepabsentProgrammatic current step. Always pair it with data-state="current".
typeaction buttonsbutton (or submit)—Use type="button" when the application handles the transition; type="submit" when the step is a native form submission.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-wizardBlock class—Bordered root section.
.forma-wizard__actionsElement class—Footer flex row with actions at opposite ends; wraps when needed.
.forma-wizard__bodyElement class—Padded region for the current step's content.
.forma-wizard__headerElement class—Grid of position/title and a progress column (at least 10rem); stacks below 40rem.
.forma-wizard__positionElement class—Small monospace "Step n of m" text.
.forma-wizard__stepsElement class—Four-column step rail with a bottom rule. Each item has a circular number marker. Below 40rem only the current item is shown.
[data-state]Attribute hook—On step items: current or complete. Presentation only; the workflow state lives in Limen/Ordo.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through the step body's fields and then the footer actions. The step rail is not interactive.
Enter / SpaceActivates the focused action button (native).
Events
EventDescription
click / submitNative events from the action buttons. Limen asks Ordo whether the transition is legal, then renders the next state.

Form behavior

The wizard is not a form itself. Wrap the body and actions in a form when steps submit natively; each step's fields validate as ordinary form controls.

States

Wizard states
StateHow it is expressedPresentation
Upcoming stepli without data-stateSecondary text and an outlined marker.
Current stepdata-state="current" + aria-current="step"Primary bold text and an inverse marker; the only step shown below 40rem, with a Current step note.
Complete stepdata-state="complete"A check glyph is generated on the marker.
Blockedapplication renders a validation summary and aria-invalid fieldsPosition and rail stay on the current step; Forma adds no rail error state.
Resumedapplication renders saved stateIdentical to any other state; resume messaging is body content.

Accessibility

Forma provides

  • States the position in text, in a native progress element and in an ordered list with aria-current="step".
  • Keeps the current step identifiable without color (bold text and inverted marker).
  • Keeps footer actions as native buttons at 44px height.

Your application supplies

  • Keep the position text, progress value/max, data-state and aria-current in sync with the workflow state.
  • Move focus to the step heading after advancing, and to the Validation summary when an advance is refused.
  • Explain in the body when steps were added or skipped by branching.
  • Do not let the rail imply that earlier steps are navigable unless the application supports it.

Responsive behavior

  • Wide: header in two columns; the rail is a four-column grid, so it is designed for four steps (additional steps wrap onto a new row).
  • Below 40rem: header stacks, rail reduces to the current step, actions wrap.
  • The body is ordinary flow content and wraps normally.

Motion

  • No animation: step changes, progress and the rail update immediately when the application renders the new state. Button hover and press use the foundation's perceptual background interpolation.

Usage guidance

Do

  • Name steps with short nouns and keep the count stable where possible.
  • Offer Save and exit on long workflows and tell users where to resume.

Avoid

  • Deciding in the UI whether a transition is legal; ask Ordo.
  • Hiding the only explanation of a blocked advance in the rail.

Verification specimens

Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.