# Sonner

A native toast engine with themes, types, promises, and responsive positioning.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<DocsBaseSwitcher base="web" component="sonner" />

<ComponentPreview name="sonner" title="sonner.tsx" previewClassName="h-auto py-16">
<SonnerDemo />
</ComponentPreview>

Toasts display brief notifications at the edge of the screen. Frakment wraps Sonner with theme-aware icons and tokens, so the look matches the rest of the registry.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
~~~bash
npx frakment add sonner
~~~
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Install the following dependencies:
</Step>

~~~bash
npm install next-themes
~~~

<Step>
Copy and paste the following code into your project.
</Step>

<ComponentSource name="sonner" title="components/ui/sonner.tsx" />

<Step>
Render the Toaster once in your root layout.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

~~~tsx title="sonner.tsx"
import { Toaster, toast } from "@/components/ui/sonner";
~~~

~~~tsx title="app/layout.tsx"
<Toaster position="top-center" />
~~~

~~~tsx
<Button onClick={() => toast("Event created")}>Show toast</Button>
~~~

## Types [#types]

Sonner ships five message types. Each picks an icon from the theme automatically.

<ComponentPreview name="sonner-types" title="sonner-types.tsx" src="examples/sonner-types.tsx" previewClassName="h-auto py-16">
<SonnerTypes />
</ComponentPreview>

~~~tsx
toast.success("Saved");
toast.error("Failed");
toast.info("Heads up");
toast.warning("Careful");
~~~

## Promise [#promise]

`toast.promise` switches the message as a promise resolves or rejects.

<ComponentPreview name="sonner-promise" title="sonner-promise.tsx" src="examples/sonner-promise.tsx" previewClassName="h-auto py-16">
<SonnerPromise />
</ComponentPreview>

~~~tsx
toast.promise(createEvent(), {
  loading: "Creating event…",
  success: (d) => \`\${d.name} created\`,
  error: "Could not create",
});
~~~

## Custom position [#custom-position]

Default position is responsive: `top-center` on mobile and `bottom-right` on desktop. Override per toast with `position`, or set a fixed position on `<Toaster position="..." />` to disable responsive behavior.

<ComponentPreview name="sonner-position" title="sonner-position.tsx" src="examples/sonner-position.tsx" previewClassName="h-auto py-16">
<SonnerPosition />
</ComponentPreview>

~~~tsx
toast("Saved", { position: "top-left" })
~~~

## Motion [#motion]

Toasts animate with CSS transitions: enter, exit, and height use 400ms ease, and swipe-out uses 200ms. Pass `motion` on `<Toaster>` to override duration and easing without editing the file:

~~~tsx
<Toaster motion="200 cubic-bezier(0.22, 1, 0.36, 1)" />
~~~

| Value | Result |
| :-- | :-- |
| omitted | 400ms ease (default) |
| `"200"` | 200ms ease-in-out |
| `"200 ease-out"` | 200ms custom easing |
| `"300 cubic-bezier(...)"` | 300ms custom cubic-bezier |
| `"off"` | no transition |

When `prefers-reduced-motion` is set, the transition is disabled regardless of the value.

### Using your own animation library [#using-your-own-animation-library]

The CSS engine lives inside `sonner.tsx` as the `sonnerStyles` constant. To swap it for GSAP, Framer Motion, or the Web Animations API, edit that constant and the `Toast` render function directly. The `motion` prop covers CSS transitions only; a third-party engine bypasses it entirely.

## In Context [#in-context]

### Toast demo [#toast-demo]

The demo on this page fires `toast` calls from a client component. Each call renders a stacked notification with a title, optional description, and auto-dismiss.

<ComponentPreview name="sonner-demo" title="sonner-demo.tsx" src="examples/sonner-demo.tsx">
<SonnerDemo />
</ComponentPreview>

## API Reference [#api-reference]

### Toaster [#toaster]

<PropsTable rows={[{"name":"position","type":"string","default":"bottom-right","description":"Screen corner where toasts stack."},{"name":"theme","type":"light | dark | system","default":"system","description":"Color scheme; follows next-themes by default."},{"name":"richColors","type":"boolean","default":"false","description":"Use stronger background colors per type."},{"name":"closeButton","type":"boolean","default":"false","description":"Show a close button on each toast."},{"name":"motion","type":"string","default":"400","description":"Animation duration and easing for enter, exit, and swipe."}]} />

## Accessibility [#accessibility]

- Each toast is announced via `aria-live="polite"`.
- Errors use `aria-live="assertive"` automatically.
- Dismiss with `toast.dismiss()` or the close button when enabled.

## Anatomy [#anatomy]

```tsx title="sonner.tsx"
import { Toaster, toast } from "@/components/ui/sonner";

<Toaster />
toast("Saved");
```

- **Toaster** — fixed viewport stack, rendered once near the root
- **Toast** — a single notification with title, description, and optional action

## Best Practices [#best-practices]

- **One Toaster per app.** Nesting causes duplicate stacks.
- **Keep messages short.** Title fits in one line.
- **Use `toast.error` for failures.** Do not use `toast` with custom styles.
- **Auto-dismiss after 4 seconds.** Persistent toasts need an explicit close.