Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Basic flow

A wizard owns its step state and runs Back, Next and Finish, so you supply only the panels in order.

Three steps, one optional

Account step content.

Profile step content, this one can be skipped.

Review step content.

Show code
<app-wizard>
    <app-wizard-step label="Account" description="Email &amp; password">
        <p>Account step content.</p>
    </app-wizard-step>
    <app-wizard-step label="Profile" description="Optional details" optional="true">
        <p>Profile step content, this one can be skipped.</p>
    </app-wizard-step>
    <app-wizard-step label="Review" description="Confirm and submit">
        <p>Review step content.</p>
    </app-wizard-step>
</app-wizard>

Header variants

Pick the header that suits the space: journey for a wide bar, icons for large badges, tiles for a row of cards.

Journey bar

Account step content.

Profile step content, this one can be skipped.

Review step content.

Show code
<app-wizard variant="Journey">…</app-wizard>
Icons

General information about the project.

Define the site and its structure.

Lay out the supply lines.

Configure the zone structure.

Run the analysis.

Review the result.

Show code
<app-wizard variant="Icons" active="1">
    <app-wizard-step label="General Info" icon="info">…</app-wizard-step>
    <app-wizard-step label="Site &amp; Structure" icon="building">…</app-wizard-step>
    <app-wizard-step label="Supply Lines" icon="zap">…</app-wizard-step>
    <app-wizard-step label="Zone Structure" icon="layout-grid">…</app-wizard-step>
    <app-wizard-step label="Analysis" icon="chart-column">…</app-wizard-step>
    <app-wizard-step label="Result" icon="shield-check">…</app-wizard-step>
</app-wizard>
Tiles

Site panel.

Structure panel.

Services panel.

Protection panel.

Review panel.

Show code
<app-wizard variant="Tiles" done-tone="AccentTone.Success" active="2">
    <app-wizard-step label="Site" icon="map-pin">…</app-wizard-step>
    <app-wizard-step label="Structure" icon="building">…</app-wizard-step>
    <app-wizard-step label="Services" icon="zap">…</app-wizard-step>
    <app-wizard-step label="Protection" icon="shield-check">…</app-wizard-step>
    <app-wizard-step label="Review" icon="chart-column">…</app-wizard-step>
</app-wizard>
Forced step status
Set status on a step to force its state, instead of deriving it from the active step: done, active, pending or error.

Account panel.

Profile panel, marked as failed.

Plan panel, forced active.

Review panel.

Show code
<app-wizard variant="Journey">
    <app-wizard-step label="Account" status="AppWizardStepStatus.Done">…</app-wizard-step>
    <app-wizard-step label="Profile" status="AppWizardStepStatus.Error">…</app-wizard-step>
    <app-wizard-step label="Plan" status="AppWizardStepStatus.Active">…</app-wizard-step>
    <app-wizard-step label="Review" status="AppWizardStepStatus.Pending">…</app-wizard-step>
</app-wizard>

Size and colour

Scale the header with size, and recolour the accent with tone, with doneTone for finished steps only.

Three sizes

General Info panel.

Site & Structure panel.

Supply Lines panel.

General Info panel.

Site & Structure panel.

Supply Lines panel.

General Info panel.

Site & Structure panel.

Supply Lines panel.

Show code
<app-wizard variant="Icons" size="Sm">…</app-wizard>
<app-wizard variant="Icons" size="Md">…</app-wizard>
<app-wizard variant="Icons" size="Lg">…</app-wizard>
Tone presets

Primary (default).

Second panel.

Third panel.

Success.

Second panel.

Third panel.

Warning.

Second panel.

Third panel.

Danger.

Second panel.

Third panel.

Info.

Second panel.

Third panel.

Show code
<app-wizard>…</app-wizard>                  <!-- primary (default) -->
<app-wizard tone="AccentTone.Success">…</app-wizard>
<app-wizard tone="AccentTone.Warning">…</app-wizard>
<app-wizard tone="AccentTone.Danger">…</app-wizard>
<app-wizard tone="AccentTone.Info">…</app-wizard>
Done steps in their own colour

First panel.

Second panel.

Journey bar: completed steps green, current step primary.

Show code
<app-wizard variant="Journey" done-tone="AccentTone.Success">…</app-wizard>
Any custom colour: CSS variables
When no preset fits, set the --wui-step-* variables in a style attribute (or a product class). Here the icons wizard is recoloured to a custom purple.

General information about the project.

Define the site and its structure.

Lay out the supply lines.

Run the analysis.

Review the result.

Show code
<app-wizard variant="Icons" active="1" style="--wui-step-accent: #7c3aed; --wui-step-soft: #efe7fd; --wui-step-soft-fg: #5b21b6;">…</app-wizard>

Validation and skipping

Gate Next with a check before a step moves on, and let an optional step be skipped without validation.

Block Next until a checkbox is ticked

You must accept the terms before continuing.

Enter your payment details.

Review and submit.

Show code
<app-wizard id="gated-wizard">
    <app-wizard-step label="Terms">
        <input type="checkbox" id="gated-terms" /> I accept the terms
    </app-wizard-step>
    <app-wizard-step label="Payment">…</app-wizard-step>
    <app-wizard-step label="Confirm">…</app-wizard-step>
</app-wizard>

<script>
    document.getElementById('gated-wizard')
        .addEventListener('wui-wizard:beforechange', function (e) {
            if (e.detail.index === 0 && !document.getElementById('gated-terms').checked) {
                e.preventDefault(); // blocks Next; step turns red, wui-wizard:invalid fires
            }
        });
</script>
beforeNext returning a Promise
The element also exposes a beforeNext property, the same one React sets from its prop, that can return a Promise. The wizard awaits it before advancing or flagging the step invalid. Here it simulates a 600 ms server-side terms check.

An async check (simulated 600ms request) must resolve true before Next advances.

Enter your payment details.

Review and submit.

Show code
<app-wizard id="async-gated-wizard">…</app-wizard>

<script>
    var wiz = document.getElementById('async-gated-wizard');
    wiz.beforeNext = function (index) {
        if (index !== 0) return true;
        return new Promise(function (resolve) {
            setTimeout(function () { resolve(termsChecked); }, 600);
        });
    };
</script>
Skip an optional step
Reserve optional for genuinely skippable steps. Use it for a step whose data can be filled in later (a profile photo, a secondary contact), not for a step that is merely short. A skipped required step should fail validation on Finish, not silently pass.

Account panel.

Profile panel, click Skip to move on without filling this in.

Review panel.

Show code
<app-wizard id="skip-wizard">
    <app-wizard-step label="Account">…</app-wizard-step>
    <app-wizard-step label="Profile" optional="true">…</app-wizard-step>
    <app-wizard-step label="Review">…</app-wizard-step>
</app-wizard>

<script>
    document.getElementById('skip-wizard')
        .addEventListener('wui-wizard:skip', function (e) {
            // e.detail.index = the skipped step
        });
</script>

Every option

Every value of every prop, one cell each.

steps: status, all four

status="done"

Forced status panel.

Second panel.

status="active"

Forced status panel.

Second panel.

status="pending"

Forced status panel.

Second panel.

status="error"

Forced status panel.

Second panel.

steps: optional, description, icon

optional: Skip shows while the step is active

Account panel.

Profile panel, optional.

Review panel.

description: a line under the label

Account panel.

Profile panel.

Review panel.

icon: a glyph in place of the number

General information.

Site and structure.

Supply lines.

key: a stable React key, no visible effect (Razor has no key attribute)

Account panel.

Profile panel.

Review panel.

children: the panels

children: one panel per step, in step order

Account panel.

Profile panel.

Review panel.

defaultActive and active: the starting step

defaultActive: React only, Razor starts the wizard with active

Account panel.

Profile panel.

Review panel.

active="0" (default)

Account panel.

Profile panel.

Review panel.

active="1"

Account panel.

Profile panel.

Review panel.

active="2"

Account panel.

Profile panel.

Review panel.

active="1": sets the starting step

Account panel.

Profile panel.

Review panel.

callbacks: what each one reports

wui-wizard:change: fires on every step change

Account panel.

Profile panel.

Review panel.

wui-wizard:finish: fires when Finish is pressed

Account panel.

Profile panel.

Review panel.

wui-wizard:skip: fires when an optional step is skipped

Account panel.

Profile panel, optional.

Review panel.

wui-wizard:beforechange: preventDefault blocks Next

Account panel. Next is blocked here.

Profile panel.

Review panel.

wui-wizard:invalid: fires when a gate blocks Next

Account panel. Next is blocked here.

Profile panel.

Review panel.

wui-wizard:close: fires when the top bar close button is pressed

Account panel.

Profile panel.

Review panel.

variant: all four

variant="steps" (default)

Account panel.

Profile panel.

Review panel.

variant="journey"

Account panel.

Profile panel.

Review panel.

variant="icons"

Account panel.

Profile panel.

Review panel.

variant="tiles"

Account panel.

Profile panel.

Review panel.

icon-variant: the six iconsax styles

icon-variant="linear" (default)

General information.

Site and structure.

Supply lines.

icon-variant="outline"

General information.

Site and structure.

Supply lines.

icon-variant="bold"

General information.

Site and structure.

Supply lines.

icon-variant="bulk"

General information.

Site and structure.

Supply lines.

icon-variant="broken"

General information.

Site and structure.

Supply lines.

icon-variant="twotone"

General information.

Site and structure.

Supply lines.

tone: all five

tone="primary" (default)

Account panel.

Profile panel.

Review panel.

tone="success"

Account panel.

Profile panel.

Review panel.

tone="warning"

Account panel.

Profile panel.

Review panel.

tone="danger"

Account panel.

Profile panel.

Review panel.

tone="info"

Account panel.

Profile panel.

Review panel.

done-tone: all five

done-tone="primary"

Account panel.

Profile panel.

Review panel.

done-tone="success"

Account panel.

Profile panel.

Review panel.

done-tone="warning"

Account panel.

Profile panel.

Review panel.

done-tone="danger"

Account panel.

Profile panel.

Review panel.

done-tone="info"

Account panel.

Profile panel.

Review panel.

orientation

orientation="horizontal" (default)

Account panel.

Profile panel.

Review panel.

orientation="vertical"

Account panel.

Profile panel.

Review panel.

align

align="center" (default)

Account panel.

Profile panel.

Review panel.

align="start"

Account panel.

Profile panel.

Review panel.

size: sm, md, lg

size="sm"

General information.

Site and structure.

Supply lines.

size="md" (default)

General information.

Site and structure.

Supply lines.

size="lg"

General information.

Site and structure.

Supply lines.

icon-size: every header glyph in px

(default) follows size

General information.

Site and structure.

Supply lines.

icon-size="12"

General information.

Site and structure.

Supply lines.

icon-size="24"

General information.

Site and structure.

Supply lines.

standalone flags

skippable="true": Skip on every non-last step

Account panel.

Profile panel.

Review panel.

non-linear="true": every header step is clickable

Account panel.

Profile panel.

Review panel.

hide-stepper="true": footer navigation only, no header

Account panel.

Profile panel.

Review panel.

hide-connectors="true": no line between the steps

Account panel.

Profile panel.

Review panel.

disabled="true": header and footer navigation both inert

Account panel.

Profile panel.

Review panel.

label: the accessible name

label="Signup progress": names the stepper for screen readers

Account panel.

Profile panel.

Review panel.

custom footer labels

back-label="Previous"

Account panel.

Profile panel.

Review panel.

next-label="Continue"

Account panel.

Profile panel.

Review panel.

finish-label="Done"

Account panel.

Profile panel.

Review panel.

skip-label="Later"

Account panel.

Profile panel. Click Later to skip.

Review panel.

top-bar, bar-title and close-label

top-bar="true": a 56px bar with Step N of M and a close button

Account panel.

Profile panel.

Review panel.

bar-title="Set up account"

Account panel.

Profile panel.

Review panel.

close-label="Dismiss"

Account panel.

Profile panel.

Review panel.

className: extra classes

class="mt-2": extra classes on the wizard

Account panel.

Profile panel.

Review panel.

Guidance

What to do, and what to avoid.

Use it when

  • A task is genuinely split across several ordered screens and each one is a real step, not just a tab.
  • You need the standard Back / Skip / Next / Finish footer wired up, not just a progress indicator.
  • Some steps are optional and the user should be able to skip past them explicitly.

Reach for something else when

  • It is one form on a single screen with grouped sections. → a form built from AppFormSection, AppFormRow and AppFormActions
  • You only need to show progress, because navigation lives elsewhere (a route, a parent component). → AppStepper
  • The sections are alternative views the user switches between freely, not a sequence. → AppTabs

Reference

Try every prop, read the full list, and check keyboard and screen reader behaviour.

steps journey icons tiles
linear outline bold bulk broken twotone
(none) primary success warning danger info
(none) primary success warning danger info
horizontal vertical
center start
sm md lg

Account panel.

Profile panel, optional, shows Skip.

Review panel.

React, generated from the controls
<AppWizard steps={steps}>
{panels}
</AppWizard>
Razor, the same props
<app-wizard>
  …
</app-wizard>

23 props. The 4 most used come first.

Used on most screens 4 props

PropTypeDefaultDescription
activedefault 0 int 0 The current step's index when the wizard is controlled, used together with onStepChange.
variantdefault steps steps | journey | icons | tiles steps The stepper header style: compact circles, the wide journey bar, large connected icon badges with a STEP n eyebrow, or a row of tiles with an icon square, a label and a Done, Current or To do line.
orientationdefault horizontal horizontal | vertical horizontal Lays the stepper out as a row or as a column.
non-lineardefault false bool false Allows jumping to any step, not only completed ones.

Less common 19 props

PropTypeDefaultDescription
icon-variantdefault linear linear | outline | bold | bulk | broken | twotone linear The iconsax style of every header glyph: the done tick, the error alert, the skipped dash and each step's own icon. Unset draws the linear style.
tonedefault - primary | success | warning | danger | info - Recolours the whole stepper accent (active fill, done rail, ring, done tint) to a semantic ramp. Unset keeps the variant's default: primary for steps and journey, success for icons.
done-tonedefault - primary | success | warning | danger | info - Recolours completed steps only (their badge, STEP n eyebrow and the filled line after them). The current step keeps the tone accent; unset, completed steps follow tone.
sizedefault md sm | md | lg md Scales the stepper header: the badge, its number, the labels and the glyphs.
icon-sizedefault - int - Every header glyph's width and height in px. Unset, it follows size (14, 16 or 20).
skippabledefault false bool false Shows a Skip button on every step but the last, without needing optional on each step.
aligndefault center center | start center Where each step's badge, label and description sit in its column on a horizontal stepper: centred, or at the start with the line running from badge to badge. It applies to the steps and icons variants.
hide-stepperdefault false bool false Hides the progress header.
hide-connectorsdefault false bool false Drops the line joining the steps, on every variant and orientation. Lines show by default.
disableddefault false bool false Disables all navigation.
labeldefault Progress string Progress The accessible name of the stepper.
back-labeldefault Back string Back The text of the Back button.
next-labeldefault Next string Next The text of the Next button.
skip-labeldefault Skip string Skip The text of the Skip button.
finish-labeldefault Finish string Finish The text of the Finish button on the last step.
top-bardefault false bool false Shows a 56px bar above the stepper with barTitle, Step N of M and a close button.
bar-titledefault - string - The title at the start of the top bar.
close-labeldefault Close string Close The accessible name of the top bar's close button.
app-wizard-stepdefault - child - One panel per step, in order. Attributes: label (the short label shown in the stepper; required), description (an optional line under the label), optional (shows Skip while the step is active), icon (a library icon name shown in place of the step number), status (done, active, pending or error, to force a status).

Screen reader

3 notes
  • The step list is named by label (Progress by default) and the current step carries aria-current step; a step that can be reached is a native button, the others are plain text.
  • Each step panel has role tabpanel; the panels of other steps are hidden and marked aria-hidden.
  • With topBar the close button is named by closeLabel.