On this page
@addTagHelper *, Webority.Ui.RazorRaising a toast
Call toast with a message and a variant, or add options for a title, an action or a stable id.
Actions and sticky toasts
Add an action button, keep a toast until someone closes it, or clear the whole stack at once.
Entrance and shape
Choose how a toast enters and its corners. Motion is off for people who prefer reduced motion.
Task progress
Show how far an upload or export has got, then update the same toast in place as the work advances.
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" chipoffset
offset: 16 (default), pixels from the screen edge the stack pins toclassName
class: extra class on the app-toast element, the Razor form of classNamevariant: all four
variant: 'success'variant: 'info' (default)variant: 'warning'variant: 'danger'duration: including sticky (0)
duration: 0 (sticky)duration: 3000duration: 5000 (default)duration: 10000animation: 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 onlyaction onlytitle + actionsticky + action (needs a close button)progress: determinate track
progress: 0progress: 35progress: 100id 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 linklong message, wraps inside the fixed-width cardmessage: 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 stageGuidance
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.
7 props. The 5 most used come first.
Used on most screens 5 props
| Prop | Type | Default | Description |
|---|---|---|---|
| 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
| Prop | Type | Default | Description |
|---|---|---|---|
| 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
| Prop | Type | Default | Description |
|---|---|---|---|
| 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
| Prop | Type | Default | Description |
|---|---|---|---|
| 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.