{
  "title": "Toast",
  "description": "Imperative notification system based on sonner — auto-dismiss, stacking, six positions, and a typed action slot.",
  "url": "/docs/components/toast",
  "since": "0.2.0",
  "tags": [
    "feedback"
  ],
  "platform": "both",
  "source": "---\ntitle: Toast\ndescription: Imperative notification system based on sonner — auto-dismiss, stacking, six positions, and a typed action slot.\nsince: 0.2.0\ntags: [feedback]\nplatform: both\ncategory: feedback\n---\n\nimport { BundleSize } from '@/components/bundle-size';\nimport { Preview } from '@/components/preview';\nimport { PropsTable } from '@/components/props-table';\n\n<BundleSize component=\"Toaster\" />\n\n## At a glance\n\n- Mount `<Toaster />` **exactly once** near your app root, then call the imperative `toast(...)` from anywhere.\n- Tone-specific shortcuts: `toast.success`, `toast.error`, `toast.warning`, `toast.info`, plus `toast.dismiss(id?)` and `toast.promise(...)`.\n- Web: powered by [sonner](https://sonner.emilkowal.ski) — full feature set including swipe-to-dismiss, screen-reader live region, and rich colors.\n- Native: matched API surface with the same six positions, swipe-to-dismiss, auto-dismiss, and stacking. No `if (Platform.OS === 'web')` in your code.\n- Six positions: `top-left`, `top-center` (default), `top-right`, `bottom-left`, `bottom-center`, `bottom-right`. The global anchor lives on `<Toaster position>`; any individual call may override with `toast(msg, { position })`.\n- `duration` defaults to 4000ms. Pass `Infinity` to keep a toast open until dismissed manually.\n\n## Mount the Toaster once\n\n```tsx\n// app/layout.tsx (Next.js) — or your tree root\nimport { Toaster } from '@nori-ui/core/client';\n\nexport default function Layout({ children }) {\n  return (\n    <>\n      {children}\n      <Toaster richColors />\n    </>\n  );\n}\n```\n\nThe docs site mounts a single `<Toaster richColors />` at the root — that's why every demo on this page uses the saturated tone surface. `richColors` is a Toaster-level flag, not a per-call option.\n\n## Tones, action, promise\n\nAll five tones plus an inline action button and `toast.promise` for async flows. Click \"Promise\" and watch the same card swap from the loading state to success after 1.5s.\n\n<Preview name=\"toast-basic\" />\n\n## Per-call position override\n\nThe global `<Toaster position>` sets the default anchor; any single call can override it with `toast(msg, { position: 'bottom-right' })`. Useful for one-off toasts that belong somewhere different from the rest of your UI.\n\n<Preview name=\"toast-positions\" />\n\n## Update an existing toast in place\n\nReuse the same `id` to swap a loading toast for a success/error one without spawning a second card. Useful when `toast.promise` doesn't fit the flow — chained calls, intermediate progress states, or backend events that arrive asynchronously.\n\n<Preview name=\"toast-update\" />\n\n## API\n\n```ts\ntoast(title, options?) // generic\ntoast.success(title, options?)\ntoast.error(title, options?)\ntoast.warning(title, options?)\ntoast.info(title, options?)\ntoast.message(title, options?)  // alias for the default tone\ntoast.dismiss(id?)              // dismiss specific or all\ntoast.promise(p, { loading, success, error })\n```\n\n`options` accepts `description`, `duration`, `action`, `cancel`, `tone`, `id`, `position`, `icon`, `className`. Each call returns the toast's id — pass it to `toast.dismiss(id)` later or to `toast(title, { id })` to update the existing entry.\n\n## `<Toaster>` props\n\nThe mount point is configured once near your app root. The most common knobs:\n\n- `position` — global default anchor.\n- `expand` — keep stacked toasts visible at full size instead of collapsing them. Default `false`.\n- `gap` — vertical gap between stacked toasts in pixels. Default `14`.\n- `offset` — distance from the chosen edge of the screen. Accepts a number (px) or a CSS string. Default `16`.\n- `visibleToasts` — maximum number of toasts shown at once. Older ones queue and pop in as space frees up. Default `3`.\n- `closeButton` — render a small ✕ on every toast. Default `false`. Per-call swipe-to-dismiss still works either way.\n- `richColors` — saturated tone surfaces (used on this docs site). Default `false`.\n\n```tsx\n<Toaster\n    position=\"bottom-right\"\n    expand\n    gap={8}\n    offset={24}\n    visibleToasts={5}\n    closeButton\n/>\n```\n\n## Props\n\n<PropsTable component=\"Toaster\" />\n"
}