Toast

Basic usage

The composite does not import next-themes — entry @comitor/ui has to run in apps that do not have it. In a Next app that does, pass resolvedTheme down, exactly as this page does; skip it and toasts follow the OS colour scheme instead of the theme the reader chose.

Variants

Five variants, passed as an option rather than as a method name. Each status icon is tinted with an -ink token, not the matching fill token: an icon is a non-text element that needs 3:1 against --popover, and text-warning measures 1.59:1 on the light palette against 6.51:1 for --warning-ink.

Description, action & duration

A toast carrying an action needs time to be reached — give it Number.POSITIVE_INFINITY and let the reader close it, rather than lengthening the default four seconds and hoping.

Following a promise

toastPromise() replaces one toast through loading → success → error. Its loading string defaults to the Vietnamese 'Đang xử lý…', so an English surface must pass all three strings; success and error also accept a function of the resolved value.

Dismissing

toast() returns the id it created. Keep it to close that one toast later — when the operation it reported finishes, or when the view it belonged to unmounts. Called with no argument, dismissToast() clears the whole stack.

Two toasters, two names

The package ships two toast surfaces. They are not aliases of each other, and only one may be mounted: sonner keeps a single global queue, so whichever one is on screen renders every toast() call in the app.

Reach for Toaster from @comitor/ui by default. It is the one that speaks the status vocabulary and solves icon contrast, and threading theme through is a single prop. Take SonnerToaster only when the app is already built on the shell's ThemeProvider, you would rather not pass that prop, and plain sonner toasts are enough. Either way the package's toast() drives it — the same queue, only without the tinted icons.

import { Button, toast } from '@comitor/ui'
import { SonnerToaster } from '@comitor/ui/shell'

export function Example() {
  return (
    <>
      <Button onClick={() => toast('Shipment released', { variant: 'success' })}>
        Show toast
      </Button>

      {/* Reads next-themes itself — no theme prop to thread through */}
      <SonnerToaster />
    </>
  )
}

The name is deliberate, not clumsy. Toaster and ToasterProps are already taken at entry @comitor/ui by the composite, so the shell file withholds those bare names: exported, they would be dead names — /shell only re-exports the Sonner* pair — and a later export * would either break the main entry's build or quietly open a second Toaster door. Two toasters with two names only holds while the bare name has no way out.

ToasterProps

ToasterProps is sonner's own props type, re-exported from @comitor/ui. The defaults below are the composite's where it sets one, and sonner's otherwise.

ToastOptions

The second argument to toast(). This is the package's own narrowed type — not sonner's ExternalToast — so anything outside these five keys is deliberately unavailable.

Functions

All three are client-only: they are exported from a 'use client' module, so calling one from a Server Component throws rather than failing quietly. Fire toasts from event handlers and effects.

toast(title, options?)

toastPromise(promise, messages)

dismissToast(id?)

Accessibility

• The toast region is a <section aria-live="polite">, so new messages are announced without focus moving — a toast never interrupts what someone is typing.
• Alt + T moves focus into the region (the hotkey prop), each toast is focusable, and Tab reaches its action and close controls. The combination is read out in the region's label.
• Auto-dismiss pauses while the pointer is over the stack or focus is inside it. A toast that carries an action should still set duration: Number.POSITIVE_INFINITY — a four-second window to find a button fails WCAG 2.2.1.
• The status icon is decoration and carries no accessible name. Keep the meaning in the title: “Could not reach the server”, never a bare “Failed.” tinted red.
• Icons use -ink tokens for the 3:1 non-text threshold on --popover, and the cancel button carries border-control-edge because its bg-muted fill sits only 1.07:1 off the surface — without the border it reads as plain text (WCAG 1.4.11).