# Toast

A temporary notification that appears in the corner of the screen, with success/error/warning/info types.

- Category: Core Elements
- Page: https://wunderui.com/components/toast
- Tier: Free

## Install

```bash
npx wunderui-cli add toast
```

## Import

```tsx
import { Toaster, ToastProvider, ToastViewport } from "@/components/ui/toast"
```

## Minimal usage

Then use it. Wrap your app in the Toaster once, and call the hook anywhere below it:

```tsx
import { Button } from "@/components/ui/button"
import { Toaster, useToast } from "@/components/ui/toast"

function SaveButton() {
  const toast = useToast()
  return (
    <Button onClick={() => toast.add({ type: "success", title: "Settings saved", description: "Your notification preferences were updated." })}>
      Save
    </Button>
  )
}

export function App() {
  return (
    <Toaster>
      <SaveButton />
    </Toaster>
  )
}
```

Expected result: A Save button. Pressing it slides a toast into the top right corner of the screen, and it goes away after 5 seconds.

## Usage

```tsx
import { Button } from "@/components/ui/button"
import { Toaster, useToast } from "@/components/ui/toast"

function ShowToastButton() {
  const toast = useToast()

  return (
    <Button
      variant="plain"
      onClick={() =>
        toast.add({
          type: "success",
          title: "Settings saved",
          description: "Your notification preferences were updated.",
        })
      }
    >
      Show toast
    </Button>
  )
}

export function Example() {
  return (
    <Toaster>
      <ShowToastButton />
    </Toaster>
  )
}
```

## When to use

### Use Toast for

- A short confirmation after an action: saved, copied, sent, or deleted with an Undo
- The progress of work that runs in the background, from its start to its result
- A message that needs no answer and does no harm if it goes unnoticed

### Use something else

- [Alert](https://wunderui.com/components/alert) for a message that belongs to the page and stays until the cause is fixed
- [Alert Dialog](https://wunderui.com/components/alert-dialog) for a decision people must make before they can go on

## Keyboard

A toast never takes focus from what people are doing. It joins the tab order only when people ask for it with F6.

| Key | Action |
|---|---|
| `F6` | Moves focus to the toasts, the region named Notifications. |
| `Tab` or `Shift+Tab` | Goes through each toast, then its action and its close button. |
| `Enter` or `Space` | Presses the focused action or close button. |
| `Escape` | Closes the focused toast. |

## Behavior

How toasts are added, how long they stay, how they stack and what they announce.

- **Adding a toast:** The useToast hook returns the manager of the nearest Toaster, with add, close, update, promise and the list of toasts. Adding takes a title, description, type, action, timeout and priority.
- **Timing:** A toast closes after 5 seconds, and you can set a timeout or 0 to keep it until closed. The timer pauses while the pointer is over the stack, focus is inside it or the window is in the background.
- **Stack:** The newest toast is in front, and older ones sit lower, smaller and fainter behind it. Hovering or focusing the stack spreads them into a list, and it shows three at a time.
- **Promise:** The promise helper adds a loading toast that doesn't close by itself, then turns it into the success or error toast when the promise settles. A loading toast has no coloured dot.
- **Announcing:** The viewport is a polite live region, so a screen reader reads each new toast without interrupting. Give an urgent toast high priority and it is announced as an alert.
- **Position and size:** The stack sits 16 px from the top or bottom right corner. A toast is up to 420 px wide, narrower on a small screen, and can be swiped away on touch.
- **Previews in these docs:** A toast is fixed to the screen corner. Each preview here is a framed box standing in for the screen, so toasts come in at its corner and stay inside, and it starts with one toast that stays open.
- **Opening and closing:** A toast slides in from the right while fading in, and leaves the same way, at slow speed. The stack moves into place on the same timing.
- **Reduced motion:** With reduced motion toasts don't slide or scale. They only fade in and out.

## Anatomy

- `Toaster`: The one-line setup. It wraps your app in a provider, renders the viewport and draws every toast, and you pick the corner: top right or bottom right.
- `ToastProvider`: The provider on its own, with a default timeout of 5000 ms and a stack limit of 3 toasts. Toaster already includes it.
- `ToastViewport`: The fixed region in the corner, a live region labelled Notifications that holds the stack. Toaster already renders it.
- `Toast`: One notification, a card with a border and a shadow. Older toasts sit smaller and fainter behind the newest, and hovering or focusing the stack spreads them into a list.
- `Type dot`: A small dot showing the type: green for success, red for error, yellow for warning and indigo for info.
- `Title`: The bold first line that names the outcome, such as Settings saved.
- `Description`: One line of detail under the title. It only appears when the toast has a description.
- `Action`: A text button in the link colour, such as Undo. It only appears when the toast has action props with a label and a click handler.
- `Close button`: A button named Close that closes the toast at once.
- `Content`

## Best practices

### Do

- Write the title as the outcome in a few words, such as Settings saved. Use the description only for detail people need, like what to do next.
- Offer Undo for actions people can take back, such as a delete, instead of asking them to confirm first.
- Use the promise helper for work that takes a while, so one toast goes from loading to success or error.
- Add the Toaster once, high in the app, and call the useToast hook only below it.

### Don't

- Don't use a toast for a problem people have to fix. It goes away, so keep an Alert on the page until the cause is gone.
- Don't put information in a toast that appears nowhere else. It can be missed or closed, so the result must also show on the page.
- Don't fire several toasts for one action. Merge them into one message, since the stack shows three at a time.
- Don't make many toasts stay forever with a timeout of 0. Keep that for a warning people must act on.

## API reference

### Toaster

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | React.ReactNode |  |  |
| position | "top-right" \| "bottom-right" | "top-right" | The corner the stack lives in: `top-right` or `bottom-right`. `top-right` by default. |

### ToastProvider

| Prop | Type | Default | Description |
|---|---|---|---|
| children | React.ReactNode |  |  |
| limit | number | 3 | The most toasts that are shown at once. Older ones wait behind the others and are marked `data-limited`. 3 by default. |
| timeout | number | 5000 | How long a toast stays before it closes, in milliseconds. 5000 by default; `0` keeps toasts until they are closed. A single toast can set its own `timeout`. |
| toastManager | ToastManager |  | A toast manager created outside React, so toasts can be added from code that is not a component, such as a fetch wrapper. |

### ToastViewport

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| position | "top-right" \| "bottom-right" | "top-right" | The corner the viewport is fixed to: `top-right` or `bottom-right`. `top-right` by default. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

## Examples

### Content: a title, a description or an action

```tsx
import { Button } from "@/components/ui/button"
import { Toaster, useToast } from "@/components/ui/toast"

function ShowToastButton() {
  const toast = useToast()

  return (
    <Button
      variant="plain"
      onClick={() =>
        toast.add({
          type: "success",
          title: "Settings saved",
          description: "Your notification preferences were updated.",
        })
      }
    >
      Show toast
    </Button>
  )
}

export function Example() {
  return (
    <Toaster>
      <ShowToastButton />
    </Toaster>
  )
}
```

### Lifecycle: closes by itself, stays open or follows a promise

```tsx
import { Button } from "@/components/ui/button"
import { Toaster, useToast } from "@/components/ui/toast"

function ShowToastButton() {
  const toast = useToast()

  return (
    <Button
      variant="plain"
      onClick={() =>
        toast.add({
          type: "success",
          title: "Settings saved",
          description: "Your notification preferences were updated.",
        })
      }
    >
      Show toast
    </Button>
  )
}

export function Example() {
  return (
    <Toaster>
      <ShowToastButton />
    </Toaster>
  )
}
```

## In context

### Confirm a save

The form stays where it is and the toast confirms the result in the corner. The Save button is the only trigger.

```tsx
import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { Toaster, useToast } from "@/components/ui/toast"

function ProfileForm() {
  const toast = useToast()

  return (
    <form
      className="flex flex-col gap-3"
      onSubmit={(event) => {
        event.preventDefault()
        toast.add({ type: "success", title: "Profile saved", description: "Your changes are live." })
      }}
    >
      <Input aria-label="Display name" defaultValue="Nora Lindgren" />
      <Button type="submit" variant="gradient">
        Save changes
      </Button>
    </form>
  )
}

export function Example() {
  return (
    <Toaster>
      <ProfileForm />
    </Toaster>
  )
}
```

### Undo a delete

The row is gone at once and the toast offers Undo for a few seconds. Deleting more rows stacks the toasts; hover them to see the list.

```tsx
import { useState } from "react"
import { IconButton } from "@/components/ui/icon-button"
import { Toaster, useToast } from "@/components/ui/toast"
import { Trash2 } from "lucide-react"

function ProjectList() {
  const toast = useToast()
  const [projects, setProjects] = useState(["Q4 roadmap", "Pricing experiment", "Onboarding revamp"])

  const remove = (name: string, index: number) => {
    setProjects((list) => list.filter((project) => project !== name))
    toast.add({
      title: `${name} deleted`,
      actionProps: {
        children: "Undo",
        onClick: () => setProjects((list) => [...list.slice(0, index), name, ...list.slice(index)]),
      },
    })
  }

  return (
    <ul className="flex flex-col gap-2">
      {projects.map((name, index) => (
        <li key={name} className="flex items-center justify-between gap-3 text-sm">
          {name}
          <IconButton variant="plain" aria-label={`Delete ${name}`} onClick={() => remove(name, index)}>
            <Trash2 />
          </IconButton>
        </li>
      ))}
    </ul>
  )
}

export function Example() {
  return (
    <Toaster>
      <ProjectList />
    </Toaster>
  )
}
```

### Follow an export

One promise call shows a loading toast and turns it into a success or an error when the work ends.

```tsx
import { Button } from "@/components/ui/button"
import { Toaster, useToast } from "@/components/ui/toast"

function ExportReport() {
  const toast = useToast()
  const createExport = () => new Promise((resolve) => setTimeout(resolve, 1800))

  return (
    <Button
      variant="gradient"
      onClick={() =>
        toast.promise(createExport(), {
          loading: { title: "Preparing the export" },
          success: { type: "success", title: "Export ready", description: "q4-roadmap.csv" },
          error: { type: "error", title: "The export failed", description: "Try again in a minute." },
        })
      }
    >
      Export report
    </Button>
  )
}

export function Example() {
  return (
    <Toaster>
      <ExportReport />
    </Toaster>
  )
}
```

## For AI agents

`get_component("toast")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
