Toast
A transient notification that stacks in a corner of the screen.
Usage
Basic
Mount one TxToastHost, then call toast(); hovering the stack fans it out and pauses every countdown.
Loading demo...
Dashboard Feedback Center
Toast handles transient feedback, TxTooltip explains the action, TxLoadingOverlay blocks a local refresh, and TxSpinner covers inline waits.
Loading demo...
Best Practices
- Mount one host near the app root and pass
position; extra hosts draw nothing but still cost a container and a development warning. - On non-English surfaces, pass
ariaLabelandcloseLabelto the host: screen readers name the region with the first, and the icon-only close button announces only the second. - Give task, save, sync, and retry notifications a stable
idso repeated status updates replace the previous toast. - Show persistent status with a stable
idandduration: 0, and clear it when leaving the page or when the task resolves. - Keep descriptions short; long progress, errors with recovery, and forms belong in panels, drawers, or pages.
- Back critical failures and long tasks with persistent visible copy or page-level status.
API Reference
TxToastHost Props
| Prop | Type | Default | Description |
|---|---|---|---|
position | 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' | 'bottom-right' | Corner, or edge center, the stack grows from. |
visibleToasts | number | 3 | Toasts shown at once; the rest wait transparently and move up as front ones leave. |
expand | boolean | false | Keeps the stack fanned out after the pointer leaves. |
gap | number | 14 | Pixels between toasts, also the collapsed peek. |
offset | number | 16 | Distance from the viewport edges. |
swipeToDismiss | boolean | true | Lets a drag flick a toast off toward its own edge. |
ariaLabel | string | 'Notifications' | Accessible name of the notification region. |
closeLabel | string | 'Dismiss notification' | Accessible name of each toast's close button. |
TxToastHost Exposed Methods
| Name | Type | Description |
|---|---|---|
pause | () => void | Freezes every countdown, the same as pauseToasts(). |
resume | () => void | Resumes every countdown from its remaining time, the same as resumeToasts(). |
expanded | boolean | Whether the stack is fanned out now (read-only): true when expand is set, or while the pointer or focus is inside. |
toast(options)
Import it from @talex-touch/tuffex/utils:
toast({
id?: string
title?: string
description?: string
variant?: 'default' | 'info' | 'success' | 'warning' | 'danger'
duration?: number // default: 2600, 0 = no auto dismiss
action?: {
label: string
onClick?: (id: string) => void
dismiss?: boolean // default: true — close the toast after onClick
}
}): string
dismissToast / clearToasts
import { clearToasts, dismissToast, toast } from '@talex-touch/tuffex/utils'
const id = toast({ title: 'Queued', duration: 0 })
dismissToast(id)
clearToasts()
pauseToasts / resumeToasts / toastsPaused
TxToastHost calls these on pointer and focus entry; call them yourself only to hold the stack for another reason, such as a dialog opening over it.
import { pauseToasts, resumeToasts, toastsPaused } from '@talex-touch/tuffex/utils'
pauseToasts() // every countdown freezes where it is; idempotent
toastsPaused() // => true
resumeToasts() // each toast resumes from the time it had left, not from the top
Overview
- The host teleports to
bodyas arole="region"labeledaria-label="Notifications"and a polite live region;dangerescalates torole="alert", and each toast has a close button namedDismiss notification. toast()returns the id; the sameidreplaces the existing toast and restarts timing from itsduration;duration: 0stays untildismissToast(id)orclearToasts().- The newest toast is in front, and each one behind sits back by
gappixels at 5% smaller scale; collapsed, only the front toast takes the pointer, and the host's empty area clicks through. Hidden toasts, and those collapsed behind the front one, areinert, so keyboard focus and screen readers never reach their actions or close buttons. - Pointer or keyboard focus entering the stack expands it and calls
pauseToasts(); leaving collapses it and callsresumeToasts(). - Dragging toward the anchored edge dismisses past 45px, or past 12px for a flick faster than 0.32px/ms; the other way moves a fifth as far and springs back, and a drag that starts on a button goes to the button.
- Only the first host to mount draws; later hosts render an empty container so hydration matches, and warn in development. When the owner unmounts, the next takes over; toasts appear the tick after mount.
Technologies
- Toasts enter and leave along their position's axis over 0.4s, and only fade under reduced motion; every call raises the host through the shared z-index manager.
- The utilities live in
packages/tuffex/packages/utils/toast.ts, and the single-host claim insrc/toast/src/host-registry.ts. - Source:
packages/tuffex/packages/components/src/toast/.
查看源码
packages/tuffex/packages/components/src/toast/index.ts