Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

Raising a toast

Call toast with a message and a variant, or add options for a title, an action or a stable id.

Toast variants
Show code
WUI.toast('Project saved', { variant: 'success' });
WUI.toast('Note this', { variant: 'info' });
WUI.toast('Changes not saved', { variant: 'warning', title: 'Warning' });
WUI.toast('Server unreachable', { variant: 'danger' });

Actions and sticky toasts

Add an action button, keep a toast until someone closes it, or clear the whole stack at once.

Action, sticky and rich body
Show code
WUI.toast('File moved to trash', { action: { label: 'Undo', onClick: restoreItem } });
WUI.toast('Processing…', { duration: 0, variant: 'info', title: 'In progress' });
WUI.toast('Export ready: download it.', { variant: 'success', title: 'Export', html: 'Export ready: <a href="#AppToast">download it</a>.' });
Clear the stack
Show code
for (let i = 1; i <= 6; i++) WUI.toast('Uploading file ' + i, { variant: 'info' });
WUI.dismissAllToasts();

Entrance and shape

Choose how a toast enters and its corners. Motion is off for people who prefer reduced motion.

Four entrances
Show code
WUI.toast('Soft rise', { variant: 'info' });
WUI.toast('Changes saved', { variant: 'success', animation: 'organic' });
WUI.toast('Boing', { variant: 'info', animation: 'jelly' });
WUI.toast('Sprung up', { variant: 'info', animation: 'spring' });
Corners and surface
Show code
WUI.toast('Pill shape', { variant: 'success', animation: 'organic', shape: 'pill' });
WUI.toast('Sharp corners', { variant: 'info', shape: 'sharp' });
WUI.toast('Always contrasts with the page', { variant: 'success', title: 'Inverse surface', surface: 'inverse' });

Task progress

Show how far an upload or export has got, then update the same toast in place as the work advances.

Upload with progress
toast.promise() is React only: a loading toast that swaps to success or error when a promise settles. On Razor, call WUI.toast() yourself at each stage, refreshing the same toast by its id as this example does.
Show code
WUI.toast('Please wait while we upload your file.', {
    id: 'upload', duration: 0, variant: 'info',
    title: "Uploading 'toasts-FINAL06.fig'", progress: 20,
    action: { label: 'Cancel', onClick: cancelUpload }
});
// later, same id, updates in place:
WUI.toast('Upload complete', { id: 'upload', variant: 'success', progress: 100, duration: 4000 });

Every option

Every value of every prop, one cell each.

position: all seven

position: 'top-start'
position: 'top-center'
position: 'top-end'
position: 'middle-center'
position: 'bottom-start'
position: 'bottom-center'
position: 'bottom-end' (default)

maxVisible

maxVisible: 4 (default), older toasts collapse to a "+N more" chip

offset

offset: 16 (default), pixels from the screen edge the stack pins to

className

class: extra class on the app-toast element, the Razor form of className

variant: all four

variant: 'success'
variant: 'info' (default)
variant: 'warning'
variant: 'danger'

duration: including sticky (0)

duration: 0 (sticky)
duration: 3000
duration: 5000 (default)
duration: 10000

animation: all four entrances

animation: 'rise' (default)
animation: 'organic'
animation: 'jelly'
animation: 'spring'

shape: all three corner treatments

shape: 'rounded' (default)
shape: 'pill'
shape: 'sharp'

surface: auto vs inverse

surface: 'auto' (default)
surface: 'inverse'

title & action

title only
action only
title + action
sticky + action (needs a close button)

progress: determinate track

progress: 0
progress: 35
progress: 100

id re-raise: in-place update

id: 'demo-cell' (first call, creates the toast)
id: 'demo-cell' (second call, replaces the first in place)

message body: rich content & overflow

html: '…', trusted markup body with a link
long message, wraps inside the fixed-width card
message: a React node, rich body with a link (React only, Razor uses html)

async: toast.promise

toast.promise(promise, { loading, success, error }) is React only; on Razor call WUI.toast at each stage

Guidance

What to do, and what to avoid.

Use it when

  • A brief confirmation or error that should not interrupt the flow ("Saved", "Copied").
  • A background result the user should notice but does not have to act on right away.

Reach for something else when

  • A message that must be acknowledged before continuing. → AppConfirmDialog
  • A persistent, in-context validation or status message. → AppAlert
  • An explanatory aside that stays on the page. → AppAlert with accent and role none

Reference

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

info success warning danger
top-start top-center top-end middle-center bottom-start bottom-center bottom-end
rise organic jelly spring
rounded pill sharp
auto inverse
React, generated from the controls
<AppToast position="bottom-end" maxVisible={4} />

toast('Playground toast', { id: 'playground-toast' });
Razor, the same props
WUI.toast('Playground toast');

7 props. The 5 most used come first.

Used on most screens 5 props

PropTypeDefaultDescription
positiondefault bottom-end TopStart | TopCenter | TopEnd | MiddleCenter | BottomStart | BottomCenter | BottomEnd bottom-end Which corner or edge of the screen the toasts stack in.
max-visibledefault 4 int 4 Most toasts shown at once. Older ones collapse to a "+N more" chip.
animationdefault rise Rise | Organic | Jelly | Spring rise Default entrance motion for every toast: rise (soft fade and lift), organic (surface materializes, status icon grows from a dot, message trails in), jelly (squash-and-stretch drop), spring (elastic slide-up). A per-toast animation option overrides it.
shapedefault rounded Rounded | Pill | Sharp rounded Default corner treatment. A per-toast shape option overrides it.
surfacedefault auto Auto | Inverse auto inverse renders every toast on the opposite surface of the active mode: a dark card in light mode, a light card in dark mode, so the stack always contrasts with the page. A per-toast surface option overrides it.

Less common 2 props

PropTypeDefaultDescription
offsetdefault 16 int 16 Distance in pixels from the screen edge the stack pins to, top or bottom. Ignored for middle-center and the side edges. The default is the --wui-toast-edge-offset token.
close-labeldefault Close string Close The close button's accessible name on every toast, for other languages.

Options for each toast, passed as the second argument of WUI.toast(message, options). All properties are optional.

10 props. The 3 most used come first.

Used on most screens 3 props

PropTypeDefaultDescription
animationdefault rise rise | organic | jelly | spring rise Entrance motion. Overrides the app-toast animation host default.
shapedefault rounded rounded | pill | sharp rounded Corner treatment. Overrides the app-toast shape host default.
surfacedefault auto auto | inverse auto inverse renders the toast on the opposite surface of the active mode (a dark card in light mode). Overrides the app-toast surface host default.

Less common 7 props

PropTypeDefaultDescription
variantdefault info success | info | warning | danger info Drives the variant icon + its tint.
titledefault - string - Optional bold first line above the message.
durationdefault 5000 number (ms) 5000 Auto-dismiss delay. Use 0 for sticky or persistent toasts (stays until manually dismissed).
actiondefault - object - Optional action button: { label, onClick } where onClick is a function. Dismissed after click.
iddefault - string - Optional explicit id. A toast with the same id replaces any existing one instead of stacking.
htmldefault - string - Trusted HTML body (links, formatting) in place of the plain-text message. Author-controlled only. Never pass user input.
progressdefault - number (0 to 100) - Determinate task-progress track and percent in the body. Pair with duration: 0 and an id, then re-raise with the same id, and the toast updates in place.

Call: WUI.toast(message, options). message is plain text, or use the html option for a trusted markup body. options = {variant, title, duration, action: {label, onClick}, id, html, animation, shape, surface, progress}.

Sticky: duration: 0 keeps the toast until it is dismissed.

Dedup: id replaces any existing toast with the same id in place instead of stacking.

Clear all: WUI.dismissAllToasts() removes every toast, for example on navigation.

Screen reader

3 notes
  • Each toast is a live region: warning and danger toasts use role alert and announce assertively, success and info toasts use role status and announce politely, and the whole message is read at once.
  • Every toast carries a status icon as well as its colour, and a close button named Close.
  • The auto-dismiss countdown pauses on hover and focus, and a toast with duration 0 stays until it is closed.