Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Compact steps

The default: a numbered circle above each label, sized to sit inside a form card above its fields.

Default steps
Show code
<app-stepper>
    <app-step label="Add site" status="AppStepStatus.Done" />
    <app-step label="Add zones" status="AppStepStatus.Done" />
    <app-step label="Risk assessment" status="AppStepStatus.Active" />
    <app-step label="Create report" />
</app-stepper>

Journey bar

Use the wide bar for a page masthead above the whole flow, where there is room for full step names.

Journey variant
Show code
<app-stepper variant="Journey">
    <app-step label="Add site" status="AppStepStatus.Done" />
    <app-step label="Add zones" status="AppStepStatus.Done" />
    <app-step label="Risk assessment" status="AppStepStatus.Active" />
    <app-step label="Create report" />
</app-stepper>

Progress from active

Pass one active index and the statuses follow, so steps before it are done and the rest pending.

Active step index
Show code
<app-stepper active="2">
    <app-step label="Add site" />
    <app-step label="Add zones" />
    <app-step label="Risk assessment" />
    <app-step label="Create report" />
</app-stepper>
A failed step
Show code
<app-stepper>
    <app-step label="Add site" status="AppStepStatus.Done" />
    <app-step label="Payment" status="AppStepStatus.Error" />
    <app-step label="Confirm" />
</app-stepper>

Details and sizes

Add a description and an icon to each step, and choose a size that fits the space the stepper has.

Descriptions and icons
Show code
<app-stepper variant="Journey">
    <app-step label="Account" description="Email &amp; password" icon="user" status="AppStepStatus.Done" />
    <app-step label="Payment" description="Card or invoice" icon="credit-card" status="AppStepStatus.Active" />
    <app-step label="Confirm" description="Review the order" icon="check-circle" />
</app-stepper>
Three sizes
Show code
<app-stepper size="Sm">…</app-stepper>
<app-stepper size="Md">…</app-stepper>
<app-stepper size="Lg">…</app-stepper>

Orientation and tone

Stack the steps down a side rail for a narrow column, and recolour the active steps with the info tone when needed.

Vertical steps
Show code
<app-stepper orientation="Vertical">
    <app-step label="Account" description="Email &amp; password" status="AppStepStatus.Done" />
    <app-step label="Company" description="Legal name &amp; tax id" status="AppStepStatus.Active" />
    <app-step label="Billing" description="Card or invoice" />
    <app-step label="Review" />
</app-stepper>
Primary and info tones
Show code
<app-stepper tone="Primary" active="1">…</app-stepper>
<app-stepper tone="Info" active="1">…</app-stepper>

Clickable steps

Let each step link back to its stage, so a person can return to an earlier step from the stepper.

Steps that link back
Show code
<app-stepper>
    <app-step label="Add site" status="AppStepStatus.Done" href="#site" />
    <app-step label="Add zones" status="AppStepStatus.Done" href="#zones" />
    <app-step label="Risk assessment" status="AppStepStatus.Active" href="#assess" />
    <app-step label="Create report" href="#report" />
</app-stepper>

Every option

Every value of every prop, one cell each.

steps: status, every value

status="done"
status="active"
status="pending"
status="error"

steps: href, every form

(no href) renders a div
href renders a link
href + status="active", aria-current on the link

steps: description

variant="steps", description under the label
variant="journey", description inside the text block
(no description)

steps: icon, and what overrides it

icon="credit-card" (pending)
icon="credit-card" status="done" (icon suppressed by the tick)
icon="credit-card" status="error" (icon suppressed by the alert)

steps: key, React only

key: React only, Razor steps have no key; a step is its order

steps: empty list

steps with no app-step children

variant: steps and journey

variant="steps" (default)
variant="journey"

orientation: horizontal and vertical

orientation="horizontal" (default)
orientation="vertical"

active: every index

active unset (default), each step keeps its own status
active="0"
active="1"
active="2"
active="3"

icon-variant: the six iconsax styles

icon-variant="linear" (default)
icon-variant="outline"
icon-variant="bold"
icon-variant="bulk"
icon-variant="broken"
icon-variant="twotone"

size: sm, md, lg

size="sm"
size="md" (default)
size="lg"

icon-size: every step glyph in px

(default) follows size
icon-size="10"
icon-size="20"

onStepClick: React only

onStepClick: React only, a button per step; Razor links each step through href

label: the accessible name

label="Checkout", names the list for screen readers, no visible effect
(omitted) (default) Progress

step-label: the built-in step text

step-label="Step {number}" (default), journey only
step-label="Stage {number}", journey only

tone: primary and info

tone="primary" (default)
tone="info"

linkComponent: React only

linkComponent: React only, a router link; Razor links a step through href

className: extra classes on the root

class: React has className, Razor takes the class attribute; none here

Guidance

What to do, and what to avoid.

Use it when

  • A task is split across several screens and the user needs to see the shape of it.
  • Steps have a fixed order and a known count.
  • Finished steps matter: the user may want to go back and check one.

Reach for something else when

  • The sections are alternative views the user switches between freely. → AppTabs
  • It is one long form on a single screen. → the .fld-section heading
  • The number of steps is unknown or changes as the user goes. → a progress message
  • You are showing progress of a background job. → AppSpinner

Name each step by its action

Do

Label each step with the action it performs, and mark exactly one step active. Three to five steps is the readable range.

Avoid

The label "Step 2" adds nothing: the circle already says 2. The label is the only place that can tell the user what the step is for.

Reference

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

4 steps (default) icons and a failed step
linear outline bold bulk broken twotone
steps journey
horizontal vertical
sm md lg
primary info
React, generated from the controls
<AppStepper
  steps={steps}
  active={1}
  onStepClick={onStepClick}
/>
Razor, the same props
<app-stepper active="1">
    <app-step label="Add site" />
    <app-step label="Add zones" />
    <app-step label="Risk assessment" />
    <app-step label="Create report" />
</app-stepper>

14 props. The 4 most used come first.

Used on most screens 4 props

PropTypeDefaultDescription
variantdefault steps steps | journey steps steps is compact, a numbered circle above its label. journey is wide, a large dot beside a step index and a title.
orientationdefault horizontal horizontal | vertical horizontal Lay the steps out in a row or stack them down a side rail.
activedefault -1 (no derivation) int -1 (no derivation) The index of the current step. Steps before it are done, the one at it is active, the rest are pending; a step's own status still wins.
sizedefault md sm | md | lg md Scales the badge, its number, the labels and the glyphs together.

Less common 10 props

PropTypeDefaultDescription
icon-variantdefault linear linear | outline | bold | bulk | broken | twotone linear The iconsax style of every step glyph.
icon-sizedefault - int - The width and height in px of every step glyph. Unset, it follows size.
labeldefault Progress string Progress The accessible name of the list.
step-labeldefault Step {number} string Step {number} Replaces the built-in English text, for other languages. The token {number} is the step's number.
tonedefault primary primary | info primary The accent of the active and done steps.
(app-step) labeldefault - string - The step's label. Each <app-step> child is one step, in order.
(app-step) statusdefault - done | active | pending | error - Overrides the status this step would otherwise derive from active.
(app-step) hrefdefault - string - Makes the step a link back to that stage, only for a stage the user may revisit.
(app-step) descriptiondefault - string - A secondary line under the label.
(app-step) icondefault - string - An icon name shown in the circle in place of the number (a done/error step keeps its own glyph).

Screen reader

3 notes
  • The stepper is a nav named by label, and the active step carries aria-current step, so a screen reader announces where the user is.
  • A finished step shows a tick and a failed step shows an alert glyph instead of its number, so the state is not carried by colour alone.
  • A step with href is a link and, with onStepClick in code, every step is a button; a step with neither is plain text.

Do and avoid

1 pairs

Name each step by its action

Do

Label each step with the action it performs, and mark exactly one step active. Three to five steps is the readable range.

Avoid

The label "Step 2" adds nothing: the circle already says 2. The label is the only place that can tell the user what the step is for.