Skip to content

Toast

Ephemeral notifications stacked in a corner. There are two ways to trigger them: from the HTML, with a data-ts-toast-trigger button, or from your JS with the toast() function, imported from the same taisho.core.js, with the matching variant (success, warning, danger, info). Paste the container from the example, which includes the icons for each variant. Without it, Core creates one with the first toast: toasts show up without an icon, and that first toast may not be announced by a screen reader. Each toast can carry an action (“Undo”), pauses while the pointer or focus is on it, and can be updated by id.

Feedback and status · TaishoDS Core, in plain HTML.

Examples

One working example per case. Each example is the HTML of its preview—copy it as is, and with Core’s CSS and JS loaded, it looks and works the same.

Notification on save

html

Class reference

Every value of each modifier, with its HTML ready to copy.

Variant

The color for the notice’s tone: default, success, warning, info, or danger.

New version available.
Deployment complete.
Your plan expires soon.
Changes saved.
We couldn’t process the payment.
html

Position

Which corner it appears in: top/bottom × left/center/right.

Deployment complete.
Deployment complete.
Deployment complete.
Deployment complete.
Deployment complete.
Deployment complete.
html

Action

With an action button (for example, “Undo”). Using it runs your callback and closes the toast.

Project moved to trash.
html

When to use

  • Confirming the result of something the user just did, like “Saved” or “Copied.”
  • The notification needs no response and can go away on its own after a few seconds.
  • The trigger lives in code (after an await), not in the HTML.
  • A reversible action (“Project deleted” + Undo) or a process that changes status, like “Queued” → “Building” → “Ready.”

When not to use

  • The message has to stay visible until it’s resolved → banner or note.
  • The user has to decide something before moving on → alert-dialog.
  • It’s a field error. It belongs on the field, not in a corner → field.

Do

  • Trigger them with data-ts-toast-trigger on a button or with toast() from code, and paste the container from the example. Without it, toasts show up without an icon.
  • Keep messages to one line. If you need more text (the description option), consider whether it’s really a banner or a note.
  • For an error the user has to read in full, set duration: 0 so it doesn’t go away on its own.
  • For an async operation, update the same toast by its id instead of firing one per step (toast.promise, or updateToast with the toast or its id).
  • With action, give it more time (a duration of 6000 ms or more). The toast pauses while the pointer or focus is on it, but not every user gets there in time.

Don’t

  • Don’t put the only explanation of a serious error in a toast. Once it’s gone, it doesn’t come back.
  • Don’t fire a burst of toasts for a single action.
  • Don’t put the only way to finish the task in action. If the toast goes away, so does the action.

TaishoDS Core

Needs Core’s JS, which handles focus, keyboard, and state.

Toasts are created on the fly, from a button with data-ts-toast-trigger or from your JS with toast(). The container holds the icons for each variant.

Core hooks into it through these attributes. They go in the markup, and there’s nothing to initialize.

  • data-ts-toast-container
  • data-ts-toast-dismiss-label
  • data-ts-toast-icon
  • data-ts-toast-region
  • data-ts-toast-trigger
  • data-ts-toast-variant

What it does: A queue with timers and stacking. The timer pauses while the pointer is over a toast or focus is inside it (and resumes where it left off). There’s an action button with a callback, a description (detail below the title), updateToast to change a toast by its element or its id, toast.promise(promesa, { loading, success, error }) for a single toast that goes from loading to success or error, and two live regions (polite and assertive, the latter for danger). There are two ways to trigger a toast—from the HTML, or from your JS with toast(), imported from the same taisho.core.js. Paste the example’s container, which holds the icons for each variant. Without it, Core creates one, but toasts show up without an icon.

Attribute What it does
--ts-toaster-offsetA CSS variable on the container (or any ancestor). Extra space from the position’s edge, so toasts don’t cover a fixed bar at the bottom (cookies, a player) or the top. Defaults to 0px. It adds to the margin and to the device’s env(safe-area-inset-*). Example: :root { --ts-toaster-offset: 72px }; if the bar’s height changes with the width, change the variable in a @media query. For the safe area to be non-zero, the page needs viewport-fit=cover in its viewport meta.
data-ts-toast-trigger="Texto"On a button. Clicking it shows a toast with that text.
data-ts-toast-variantOn the same button: default (the default), success, warning, info, or danger.
data-ts-toast-containerThe toast container; it holds two live regions, one polite and one assertive (data-ts-toast-region). With the <template data-ts-toast-icon="…"> elements the example includes, each variant gets its icon.
data-ts-toast-dismiss-labelOn the container. The accessible name of each toast’s close button. Without it, a Spanish default label. The dismissLabel option of toast() changes it for a single toast.
toast(message, options)From your JS. Shows a toast and returns its element. toast.promise() and updateToast() track it and change it.

From the CDN, without a build, load taisho.toast.css along with taisho.base.css. Also load:

  • taisho.button.css
  • taisho.icon.css
  • taisho.spinner.css

For how Core works in general, see Behavior.

Accessibility

  • The container ships two sibling live regions in the markup: a polite one (role="status") and an assertive one (role="alert"). They exist before the first toast, which is what lets it be announced reliably. Error toasts (the danger variant) go in the assertive region and the rest in the polite one; toasts carry no role of their own, so live regions never nest. Without the container in the markup, Core creates it along with the first toast, and that first announcement may not be read.
  • Color isn’t the only indicator. The text conveys the status, and the variant icon reinforces it when the container includes the example’s <template data-ts-toast-icon> elements. Without that container, toasts show up without an icon, and the text still states the status.
  • Adjustable timing (WCAG 2.2.1). Toasts pause while the pointer is over the toast region or focus is inside it, and resume where they left off. duration: 0 keeps them until they’re closed.
  • The action (Undo) is a real <button>. Tab reaches it, and Enter or Space activates it and closes the toast.
  • When a toast is updated by id, the new text is announced through the region it’s in. If the variant changes to an error (danger), the toast moves to the assertive region (and back to the polite one if it stops being one). During toast.promise, the toast carries aria-busy, and the Spinner is decorative (aria-hidden).

Verification

What was actually tested. Anything that wasn’t tested says so—we’d rather say “not verified” than claim too much.

  • axe WCAG 2.2 A + AA in a real browser, in light and dark mode, before every release.
  • keyboard Adds no keys of its own—it uses the browser’s native behavior.
  • screen reader Not verified with a screen reader. Test it in your own combination of components, not just here, where each one appears alone and on its happy path.