Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Variants

Solid for the main action, soft and outline for the rest, and tone danger only when the action destroys something.

Emphasis ladder
Six fills and six tones, from loudest to quietest in use.
variant=solid
variant=soft
variant=outline
variant=ghost
variant=link
tone=danger
tone=success
tone=warning
tone=info
tone=neutral
tone=danger variant=soft
tone=danger variant=outline
tone=neutral variant=outline
variant=glass, dark panel
Show code
<app-button>Save invoice</app-button>
<app-button variant="Soft">Save invoice</app-button>
<app-button variant="Outline">Save invoice</app-button>
<app-button variant="Ghost">Save invoice</app-button>
<app-button tone="Danger">Delete</app-button>

Sizes and shape

md is the default. Use sm in dense tables and toolbars, lg on sign-in screens, and xl for a marketing call to action. xl is 55px tall and steps down to 45px below 992px.

Four sizes, three corner shapes
size=sm
size=md (default)
size=lg
size=xl
shape=pill
shape=sharp
Show code
<app-button size="WideSize.Sm">Continue</app-button>
<app-button>Continue</app-button>
<app-button size="WideSize.Lg">Continue</app-button>
<app-button size="WideSize.Xl" shape="Pill">Continue</app-button>
<app-button shape="Pill">Continue</app-button>
<app-button shape="Sharp">Continue</app-button>

With icons

An icon adds meaning, never decoration. A trailing arrow means the flow moves forward.

Leading, trailing and key chip
leftIcon=add
rightIcon=arrow-right
outline with leftIcon
shortcut=N
Show code
<app-button left-icon="add">Add customer</app-button>
<app-button variant="Soft" right-icon="arrow-right">Next step</app-button>
<app-button variant="Outline" left-icon="document-download">Export GST report</app-button>
<app-button shortcut="N">New invoice</app-button>

Icon style

iconVariant picks the iconsax style of leftIcon and rightIcon: linear (the default), outline, bold, bulk, broken or twotone. It also styles the roll animation's arrow and a pinned icon.

The six icon styles
One button per style, with a left and a right icon.
Show code
<app-button variant="Soft" icon-variant="IconVariant.Linear" left-icon="heart" right-icon="arrow-right">Linear</app-button>
<app-button variant="Soft" icon-variant="IconVariant.Outline" left-icon="heart" right-icon="arrow-right">Outline</app-button>
<app-button variant="Soft" icon-variant="IconVariant.Bold" left-icon="heart" right-icon="arrow-right">Bold</app-button>
<app-button variant="Soft" icon-variant="IconVariant.Bulk" left-icon="heart" right-icon="arrow-right">Bulk</app-button>
<app-button variant="Soft" icon-variant="IconVariant.Broken" left-icon="heart" right-icon="arrow-right">Broken</app-button>
<app-button variant="Soft" icon-variant="IconVariant.Twotone" left-icon="heart" right-icon="arrow-right">Twotone</app-button>
<app-button icon-variant="IconVariant.Bulk" animation="AppButtonAnimation.Roll" right-icon="arrow-right">Bulk · roll</app-button>

Hover animation

Every button animates on hover. The default is an angled sheen sweep; choose another feel with the animation prop, or turn motion off with the value none. Every option reads on every fill and honours prefers-reduced-motion. Hover each button to compare.

Roll
animation="roll": the label rolls up while a copy rolls in from below, and a rightIcon sits in a round well and slides through it. The colours stay put.
Show code
<app-button animation="AppButtonAnimation.Roll" right-icon="arrow-right">Become a partner</app-button>
<app-button variant="Soft" animation="AppButtonAnimation.Roll" right-icon="arrow-right">See pricing</app-button>
<app-button tone="Neutral" variant="Soft" animation="AppButtonAnimation.Roll">Learn more</app-button>
Roll on every fill and size
The label roll and the icon well read on every fill, tinted from the label colour. The well is 22, 28 or 34px for sm, md and lg, and each button is as wide as its content.
Show code
<app-button variant="Solid" animation="AppButtonAnimation.Roll" right-icon="arrow-right">solid</app-button>
<app-button variant="Soft" animation="AppButtonAnimation.Roll" right-icon="arrow-right">soft</app-button>
<app-button variant="Outline" animation="AppButtonAnimation.Roll" right-icon="arrow-right">outline</app-button>
<app-button variant="Ghost" animation="AppButtonAnimation.Roll" right-icon="arrow-right">ghost</app-button>
<app-button variant="Link" animation="AppButtonAnimation.Roll" right-icon="arrow-right">link</app-button>
<app-button variant="Glass" animation="AppButtonAnimation.Roll" right-icon="arrow-right">glass</app-button>
<app-button size="WideSize.Sm" animation="AppButtonAnimation.Roll" right-icon="arrow-right">Small</app-button>
<app-button animation="AppButtonAnimation.Roll" right-icon="arrow-right">Medium</app-button>
<app-button size="WideSize.Lg" animation="AppButtonAnimation.Roll" right-icon="arrow-right">Large</app-button>
Link, no background
variant="link" is brand text with no box in any state, not even on hover, and no side padding. With animation="roll" the label rolls and the arrow slides through its well. The arrow is the text size in sm, md and lg.
Show code
<app-button variant="Link" animation="AppButtonAnimation.Roll" right-icon="arrow-right">Learn more</app-button>
<app-button variant="Link" right-icon="arrow-right">Read the guide</app-button>
<app-button variant="Link" size="WideSize.Sm" animation="AppButtonAnimation.Roll" right-icon="arrow-right">Small</app-button>
<app-button variant="Link" animation="AppButtonAnimation.Roll" right-icon="arrow-right">Medium</app-button>
<app-button variant="Link" size="WideSize.Lg" animation="AppButtonAnimation.Roll" right-icon="arrow-right">Large</app-button>
Icon pinned to the end
pinRightIcon pins the rightIcon in its round well to the end edge. The label is centred in the space before the icon, as far from the start edge as from the well, at any width.
Show code
<app-button animation="AppButtonAnimation.Roll" right-icon="arrow-right" pin-right-icon="true">Become a partner</app-button>
<app-button variant="Soft" right-icon="arrow-right" pin-right-icon="true">Continue</app-button>
<app-button block="true" animation="AppButtonAnimation.Roll" right-icon="arrow-right" pin-right-icon="true">Full width, label centred</app-button>
<app-button block="true" animation="AppButtonAnimation.Roll" right-icon="arrow-right">Full width, label and arrow centred</app-button>
Other animations
default (sheen) · fill · expand · glow · none. The moving layer tints from the button's own colour, so every option reads on solid, outline, ghost and neutral alike.
Show code
<app-button>Default sheen</app-button>
<app-button animation="AppButtonAnimation.Fill">Fill</app-button>
<app-button animation="AppButtonAnimation.Expand">Expand</app-button>
<app-button animation="AppButtonAnimation.Glow">Glow</app-button>
<app-button animation="AppButtonAnimation.None">None</app-button>
<app-button variant="Outline" animation="AppButtonAnimation.Fill">Outline · fill</app-button>
<app-button variant="Ghost" animation="AppButtonAnimation.Expand">Ghost · expand</app-button>
<app-button tone="Danger" animation="AppButtonAnimation.Glow">Danger · glow</app-button>
<app-button tone="Neutral" animation="AppButtonAnimation.Sheen">Neutral · sheen</app-button>

Loading and disabled

Loading keeps the width so the layout never jumps. Say why a button is disabled next to it.

States
default
loading
disabled
danger, disabled
Show code
<app-button>Save changes</app-button>
<app-button loading="true">Save changes</app-button>
<app-button disabled="true">Save changes</app-button>
<app-button tone="Danger" disabled="true">Delete invoice</app-button>

Loading from script

A page that submits with JavaScript calls WUI.button.setLoading(button, true) before the request and WUI.button.setLoading(button, false) after it. The button then shows the same spinner, disabled state and aria-busy as the loading attribute. A button that was disabled before loading stays disabled.

const form = document.querySelector("#order-form");
const button = form.querySelector("button[type=submit]");
WUI.button.setLoading(button, true);
try {
    await fetch(form.action, { method: "POST", body: new FormData(form) });
} finally {
    WUI.button.setLoading(button, false);
}

Busy while a form submits

A post form's submit button takes the spinner and aria-busy until the next page loads. Nothing to add.

Busy while a form submits
A post form's submit button shows a spinner and is marked busy until the next page loads. The library does this for every post form; no attribute is needed.
Show code
<form method="post" class="d-flex gap-2"><app-button type="Submit">Save changes</app-button></form>

Vibrate on tap

On a phone, a tap can buzz the device so the press is felt. The vibrate prop set to true buzzes 10 ms; a number from 1 to 100 buzzes that many milliseconds. Desktop and iOS Safari have no vibration, so nothing happens there.

Vibrate on tap (phones)
Show code
<app-button vibrate="true">Save</app-button>
<app-button variant="Outline" vibrate="40">Remove</app-button>

In context

A form footer: the primary action sits last and the way out sits beside it.

Invite a teammate
Invite a teammate
They get an email with a link that works for 7 days.
Show code
<app-card variant="Outline" title="Invite a teammate">
    <app-input label="Work email"></app-input>
    <app-button variant="Soft">Cancel</app-button>
    <app-button left-icon="send">Send invite</app-button>
</app-card>

Every option

Every value of every prop, one cell each.

children

children

tone

tone="primary" (default)
tone="success"
tone="warning"
tone="danger"
tone="info"
tone="neutral"

variant

variant="solid" (default)
variant="soft"
variant="outline"
variant="ghost"
variant="link"
variant="glass"

size

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

loading

loading="false" (default)
loading="true"
loading with left-icon (icon hidden while loading)

leftIcon

left-icon="download"
leftIcon={<AppIcon size={24} />} (React only; Razor draws the name at its size)

rightIcon

right-icon="arrow-right"
rightIcon={<AppIcon size={24} />} (React only; Razor draws the name at its size)

type

type="button" (default)
type="submit" (submits the surrounding form)
type="reset" (resets the surrounding form)

disabled

disabled="false" (default)
disabled="true"
disabled="true" tone="danger"

block

block="false" (default)
block="true": stretches to the container width

href

href="/Components/AppCard": renders a link styled as a button
disabled href (drops href, leaves tab order)

confirm

confirm="Delete this invoice?"
confirm-title="Delete invoice" (needs confirm)
confirm-label="Delete" (needs confirm)
confirm-tone="danger" (needs confirm)
confirm-tone omitted (default, plain confirmation)

static

static="false" (default)
static="true" (renders a span, not a button)
Verified

tooltip

tooltip="Saves the invoice"

tooltipPlacement

tooltip-placement="auto" (default)
tooltip-placement="top"
tooltip-placement="bottom"
tooltip-placement="start"
tooltip-placement="end"

shortcut

shortcut="A"

iconVariant

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

shape

shape="rounded" (default)
shape="pill"
shape="sharp"

pinRightIcon

pin-right-icon="false" (default)
pin-right-icon="true"

animation

animation="sheen" (default)
animation="fill"
animation="expand"
animation="glow"
animation="roll" (rolls the label; a right-icon slides through its well)
animation="none"

vibrate

vibrate omitted (default)
vibrate="true" (buzzes 10 ms, phones only)
vibrate="40" (buzzes 40 ms, phones only)

onClick

onClick={…} (React only; Razor attaches a click listener in script)

onClickCapture

onClickCapture={…} (React only)

className

class="analytics-button" (React form: className)
class="btn-anim-sheen" (the sheen, named)
class="btn-anim-fill" (a tint wipes in from the left)
class="btn-anim-expand" (a glow blooms from the centre)
class="btn-anim-glow" (a soft glow ring and lift)
class="btn-anim-none" (no hover motion)

Guidance

What to do, and what to avoid.

Use it when

  • The user performs an action: submit, save, open a dialog, confirm.
  • You need to mark the single most important action on a screen (one primary).
  • A destructive action needs to stand out (danger): pair it with a confirm dialog.
  • A form's submit button takes loading from the mutation state; that also blocks a second press.

Reach for something else when

  • It navigates to another page or URL. → a link
  • It toggles a single on/off setting. → AppSwitch
  • It is an icon-only action in a row or toolbar. → AppActionIcon
  • It is a selectable filter or tag. → AppChoiceChip

One primary action per group

Do

One clear primary action, supported by a secondary. The eye knows where to go.

Avoid

Two primaries compete for attention, so neither reads as the main action.

Name destructive actions specifically

Do

Destructive actions use danger and name the object: "Delete project", not "OK".

Avoid

A vague "Submit" in the default variant hides that this deletes data.

Start labels with an action verb

Do

Action-first verb + optional reinforcing icon. The label says exactly what happens.

Avoid

A noun-only label leaves the user guessing what the button does.

Reference

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

primary success warning danger info neutral
solid soft outline ghost link glass
sm md lg xl
button submit reset
(none) download add check trash-2
(none) arrow-right external-link chevron-down
(auto) top bottom start end
(default) linear outline bold bulk broken twotone
rounded pill sharp
(default) sheen fill expand glow roll none
(none) danger
React, generated from the controls
<AppButton>Save changes</AppButton>
Razor, the same props
<app-button>Save changes</app-button>

24 props. The 5 most used come first.

Used on most screens 5 props

PropTypeDefaultDescription
tonedefault primary primary | success | warning | danger | info | neutral primary Semantic colour.
variantdefault solid solid | soft | outline | ghost | link | glass solid Emphasis level: solid fill, soft tint, outline, ghost, link text, or glass.
sizedefault md sm | md | lg | xl md Control size. xl is a marketing call to action: 55px tall with larger text, and 45px below 992px.
loadingdefault false bool false Shows a spinner and disables the button while work runs; hides both icons.
left-icondefault - string - An icon name, or a node drawn as given.

Less common 19 props

PropTypeDefaultDescription
(content)default - string - The button label (inner content). Always a verb-led phrase.
right-icondefault - string - An icon name, or a node drawn as given.
typedefault button button | submit | reset button The native button type; not emitted on a link-shaped button.
disableddefault false bool false Disables the button.
blockdefault false bool false Full width of its container.
hrefdefault - string - Render as a button-styled link (an anchor with an href) instead of a button.
confirmdefault - string - A question to ask first, in the shared confirm dialog. The click, submit or link goes ahead only when the person confirms. Needs no page script.
confirm-titledefault - string - The confirm dialog's heading. Needs confirm.
confirm-labeldefault Confirm string Confirm The confirm button's text. Needs confirm.
confirm-tonedefault - string - The confirm button's tone. danger draws it red, for a delete or another step that cannot be undone; leave it off for a plain confirmation. An unknown value throws. Needs confirm.
staticdefault false bool false Render as a non-interactive element (a span) that keeps the button's chrome but does not click, focus or hover: a resolved or confirmation label (for example Verified) sized to sit where its action button was. Ignores loading, disabled, type and href.
tooltipdefault - string - A collision-aware hover and focus tooltip (through AppTooltip and Popper) that flips to stay on screen. For a labelled button use it sparingly, since the label already says what it does; it is most useful on a terse or icon-led action.
tooltip-placementdefault auto auto | top | bottom | start | end auto Preferred tooltip side; auto picks the side with the most room.
icon-variantdefault linear linear | outline | bold | bulk | broken | twotone linear The iconsax style of a named leftIcon / rightIcon; a node icon is drawn as given.
shapedefault rounded rounded | pill | sharp rounded Corner shape: the default rounded squircle, a fully rounded pill, or sharp square corners.
pin-right-icondefault false bool false Pin the rightIcon (or the roll animation's icon well) to the button's end edge and centre the label; for a wide or full-width button.
animationdefault - sheen | fill | expand | glow | roll | none - Hover animation; omit for the default sheen. roll rolls the label up and slides a trailing rightIcon through a round well.
shortcutdefault - string - The key that runs this action ("A", "E", "/"), drawn as a key chip: in the tooltip when the button has one, otherwise after the label. Sets aria-keyshortcuts; the page binds the key itself. Ignored on a static button.
vibratedefault - true | 1 to 100 - Phones only: true buzzes 10 ms on a tap, or a whole number of milliseconds from 1 to 100. Any other value renders nothing. Ignored on a static button.

Keyboard

5 keys
KeyDoesNotes
TabMoves focus onto the button.In page order. A disabled or loading button is skipped.
Shift + TabMoves focus to the previous control.Reverse of Tab; the order never changes.
EnterActivates the button.On a link button (href) it follows the link.
SpaceActivates the button.Runs on key up, like a native button. A link button ignores it.
The shortcut key, for example NRuns the action.Only when the page binds the key. The button exposes it as aria-keyshortcuts.

Screen reader

4 notes
  • While loading, the button shows a spinner hidden from assistive technology, sets aria-busy and is disabled.
  • A shortcut sets aria-keyshortcuts; the page binds the key itself.
  • A static button renders as a plain span, never a button, so assistive technology reads it as text.
  • The roll animation's copy of the label is aria-hidden, so the label is read once.

Contrast

WCAG 2.2, 4.5:1 for labels
PairLightDark
primary-text on primary6.29:1 AA6.29:1 AA
primary as text on bg-light6.29:1 AA6.23:1 AA
primary-hover as text on bg-light4.47:1 Large only7.36:1 AAA
danger-text on danger-104.77:1 AA4.77:1 AA
success-text on the soft success tint (the success variant)5.02:1 AASet by the dark theme
white on success-strong (solid green surfaces)5.82:1 AA5.82:1 AA
white on danger-strong (the danger variant)5.80:1 AA5.80:1 AA

Do and avoid

3 pairs

One primary action per group

Do

One clear primary action, supported by a secondary. The eye knows where to go.

Avoid

Two primaries compete for attention, so neither reads as the main action.

Name destructive actions specifically

Do

Destructive actions use danger and name the object: "Delete project", not "OK".

Avoid

A vague "Submit" in the default variant hides that this deletes data.

Start labels with an action verb

Do

Action-first verb + optional reinforcing icon. The label says exactly what happens.

Avoid

A noun-only label leaves the user guessing what the button does.