On this page
@addTagHelper *, Webority.Ui.RazorVariants
Solid for the main action, soft and outline for the rest, and tone danger only when the action destroys something.
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.
With icons
An icon adds meaning, never decoration. A trailing arrow means the flow moves forward.
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.
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.
Loading and disabled
Loading keeps the width so the layout never jumps. Say why a button is disabled next to it.
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.
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.
In context
A form footer: the primary action sits last and the way out sits beside it.
Every option
Every value of every prop, one cell each.
children
childrentone
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 widthhref
href="/Components/AppCard": renders a link styled as a buttondisabled 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)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
One clear primary action, supported by a secondary. The eye knows where to go.
Two primaries compete for attention, so neither reads as the main action.
Name destructive actions specifically
Destructive actions use danger and name the object: "Delete project", not "OK".
A vague "Submit" in the default variant hides that this deletes data.
Start labels with an action verb
Action-first verb + optional reinforcing icon. The label says exactly what happens.
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.
24 props. The 5 most used come first.
Used on most screens 5 props
| Prop | Type | Default | Description |
|---|---|---|---|
| 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
| Prop | Type | Default | Description |
|---|---|---|---|
| (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| Key | Does | Notes |
|---|---|---|
| Tab | Moves focus onto the button. | In page order. A disabled or loading button is skipped. |
| Shift + Tab | Moves focus to the previous control. | Reverse of Tab; the order never changes. |
| Enter | Activates the button. | On a link button (href) it follows the link. |
| Space | Activates the button. | Runs on key up, like a native button. A link button ignores it. |
| The shortcut key, for example N | Runs 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| Pair | Light | Dark |
|---|---|---|
| primary-text on primary | 6.29:1 AA | 6.29:1 AA |
| primary as text on bg-light | 6.29:1 AA | 6.23:1 AA |
| primary-hover as text on bg-light | 4.47:1 Large only | 7.36:1 AAA |
| danger-text on danger-10 | 4.77:1 AA | 4.77:1 AA |
| success-text on the soft success tint (the success variant) | 5.02:1 AA | Set by the dark theme |
| white on success-strong (solid green surfaces) | 5.82:1 AA | 5.82:1 AA |
| white on danger-strong (the danger variant) | 5.80:1 AA | 5.80:1 AA |
Do and avoid
3 pairsOne primary action per group
One clear primary action, supported by a secondary. The eye knows where to go.
Two primaries compete for attention, so neither reads as the main action.
Name destructive actions specifically
Destructive actions use danger and name the object: "Delete project", not "OK".
A vague "Submit" in the default variant hides that this deletes data.
Start labels with an action verb
Action-first verb + optional reinforcing icon. The label says exactly what happens.
A noun-only label leaves the user guessing what the button does.