> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.

# Sonner

Feedback`@rockshin/tao-ui`

[Examples](#examples)[API](#api)

Displays temporary toast notifications with optional actions and provider-aware theming.

## When to use

Mount one Sonner near app root, then call toast() imperatively from event handlers. Supports toast.loading(), toast.promise(), and toast.custom() for richer async and custom notification flows.

**Recommended**

- Prefer short, status-oriented messages with one primary action at most.
- Enable richColors when semantic status color should be visible.

**Avoid**

- Do not use toast notifications for blocking confirmations.

## Examples

Each example runs independently, and notifications stay inside its preview. Applications normally mount one `Sonner` host.


### Basic usage
```tsx preview="iframe-follow"
import { Button, Sonner, toast } from '@rockshin/tao-ui';

function SonnerExample() {
  return (
    <>
      <Button
        onClick={() =>
          toast.success({
            title: 'Saved',
            description: 'Your profile has been updated.',
          })
        }
      >
        Show toast
      </Button>
      <Sonner />
    </>
  );
}

export default SonnerExample;
```

### Semantic and rich-color toasts
```tsx preview="iframe-follow"
import { Button, Sonner, Stack, toast } from '@rockshin/tao-ui';

function SemanticToasts() {
  return (
    <>
      <Stack direction="horizontal" gap="sm">
        <Button
          variant="secondary"
          onClick={() =>
            toast.info({
              title: 'Info',
              description: 'A new version is ready.',
            })
          }
        >
          Info
        </Button>
        <Button
          variant="secondary"
          onClick={() => toast.success({ title: 'Saved' })}
        >
          Success
        </Button>
        <Button
          variant="secondary"
          onClick={() => toast.warning({ title: 'Almost full' })}
        >
          Warning
        </Button>
        <Button
          variant="secondary"
          onClick={() => toast.error({ title: 'Build failed' })}
        >
          Error
        </Button>
      </Stack>
      <Sonner richColors closeButton />
    </>
  );
}

export default SemanticToasts;
```

### Loading and promise lifecycle
```tsx preview="iframe-follow"
import { Button, Sonner, Stack, toast } from '@rockshin/tao-ui';

const wait = (duration: number) =>
  new Promise((resolve) => window.setTimeout(resolve, duration));

function AsyncToasts() {
  return (
    <>
      <Stack direction="horizontal" gap="sm">
        <Button
          onClick={() => {
            const id = toast.loading({ title: 'Syncing workspace' });
            window.setTimeout(() => {
              toast.dismiss(id);
              toast.success({ title: 'Workspace synced' });
            }, 1200);
          }}
        >
          Loading
        </Button>
        <Button
          variant="secondary"
          onClick={() =>
            toast.promise(wait(1200), {
              loading: { title: 'Publishing' },
              success: { title: 'Published' },
              error: { title: 'Publish failed' },
            })
          }
        >
          Promise
        </Button>
      </Stack>
      <Sonner richColors />
    </>
  );
}

export default AsyncToasts;
```

### Actions, positions, and stack limits
```tsx preview="iframe-follow"
import { Button, Sonner, Stack, toast } from '@rockshin/tao-ui';

function ActionToasts() {
  return (
    <>
      <Stack direction="horizontal" gap="sm">
        <Button
          onClick={() =>
            toast({
              title: 'Message sent',
              action: {
                label: 'Undo',
                onClick: () => toast.success({ title: 'Send reverted' }),
              },
            })
          }
        >
          With action
        </Button>
        <Button
          variant="secondary"
          onClick={() => toast.info({ title: 'Top right' })}
        >
          Positioned
        </Button>
        <Button variant="ghost" onClick={() => toast.dismiss()}>
          Dismiss all
        </Button>
      </Stack>
      <Sonner position="top-right" visibleToasts={3} closeButton />
    </>
  );
}

export default ActionToasts;
```

### Semantic colors
richColors distinguishes status notifications.
```tsx preview="iframe-follow"
import { Button, Sonner, Stack, toast } from '@rockshin/tao-ui';

export default function SonnerRichColors() {
  return (
    <>
      <Stack direction="horizontal" gap="sm">
        <Button
          onClick={() =>
            toast.info({
              title: 'Deploy started',
              description: 'We will notify you when it finishes.',
              action: { label: 'View' },
            })
          }
        >
          Info
        </Button>
        <Button
          variant="secondary"
          onClick={() =>
            toast.error({
              title: 'Build failed',
              description: 'Check logs and retry.',
              cancel: { label: 'Dismiss' },
            })
          }
        >
          Error
        </Button>
      </Stack>
      <Sonner richColors closeButton />
    </>
  );
}
```

### Notification actions
action and cancel provide related actions.
```tsx preview="iframe-follow"
import { Button, Sonner, Stack, toast } from '@rockshin/tao-ui';

export default function SonnerActions() {
  return (
    <>
      <Stack direction="horizontal" gap="sm">
        <Button
          onClick={() =>
            toast({
              title: 'Message sent',
              description: 'Your message has been delivered.',
              action: {
                label: 'Undo',
                onClick: () =>
                  toast.warning({
                    title: 'Send reverted',
                    description: 'Draft restored to composer.',
                  }),
              },
              cancel: { label: 'Dismiss' },
            })
          }
        >
          Undo toast
        </Button>
        <Button
          variant="secondary"
          onClick={() =>
            toast.warning({
              title: 'Storage almost full',
              description: 'Delete unused files or upgrade your plan.',
              action: { label: 'Manage storage' },
            })
          }
        >
          Warning action
        </Button>
      </Stack>
      <Sonner closeButton richColors />
    </>
  );
}
```

### Toast positions
Choose the toast position; notifications remain inside the preview window.
```tsx preview="iframe-follow"
import { Button, Sonner, Stack, toast } from '@rockshin/tao-ui';

export default function SonnerPositions() {
  return (
    <>
      <Stack
        direction="horizontal"
        gap="sm"
        styles={{ root: { flexWrap: 'wrap' } }}
      >
        <Button
          onClick={() =>
            toast({
              title: 'Top left',
              description: 'Positioned in the top-left corner.',
            })
          }
        >
          Trigger
        </Button>
      </Stack>
      <Sonner position="top-left" />
    </>
  );
}
```

### Stacking and visible limits
visibleToasts limits the number of simultaneously visible notifications.
```tsx preview="iframe-follow"
import { Button, Sonner, Stack, toast } from '@rockshin/tao-ui';

export default function SonnerStackAndLimit() {
  return (
    <>
      <Stack direction="horizontal" gap="sm">
        <Button
          onClick={() => {
            for (let index = 1; index <= 5; index += 1) {
              toast({
                title: `Queued task #${index}`,
                description: `Background job ${index} is now running.`,
              });
            }
          }}
        >
          Push 5 toasts
        </Button>
        <Button variant="ghost" onClick={() => toast.dismiss()}>
          Clear all
        </Button>
      </Stack>
      <Sonner visibleToasts={3} />
    </>
  );
}
```

### Toast duration
Override duration per toast and provide dismissal for persistent messages.
```tsx preview="iframe-follow"
import { Button, Sonner, Stack, toast } from '@rockshin/tao-ui';

export default function SonnerCustomDuration() {
  return (
    <>
      <Stack direction="horizontal" gap="sm">
        <Button
          onClick={() =>
            toast({
              title: 'Autosaves enabled',
              description: 'This one disappears quickly.',
              duration: 1200,
            })
          }
        >
          Short
        </Button>
        <Button
          variant="secondary"
          onClick={() =>
            toast({
              title: 'Manual review needed',
              description: 'This one stays longer for attention.',
              duration: 8000,
            })
          }
        >
          Long
        </Button>
      </Stack>
      <Sonner closeButton />
    </>
  );
}
```

### Submission feedback
A local delay simulates submission feedback for pending, success, and error states.
```tsx preview="iframe-follow"
import { Button, Sonner, Stack, toast } from '@rockshin/tao-ui';

function wait(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

export default function SonnerFormSubmit() {
  return (
    <>
      <Stack direction="horizontal" gap="sm">
        <Button
          onClick={async () => {
            await toast.promise(wait(1200), {
              loading: {
                title: 'Submitting form',
                description: 'Validating fields and saving changes.',
              },
              success: {
                title: 'Profile updated',
                description: 'Name, email, and preferences are saved.',
              },
              error: {
                title: 'Submit failed',
              },
            });
          }}
        >
          Submit profile
        </Button>
        <Button
          variant="secondary"
          onClick={() =>
            toast
              .promise(
                wait(1200).then(() => {
                  throw new Error('Card declined');
                }),
                {
                  loading: {
                    title: 'Submitting payment',
                    description: 'Contacting payment gateway.',
                  },
                  success: { title: 'Paid' },
                  error: (error) => ({
                    title: 'Payment failed',
                    description: (error as Error).message,
                  }),
                },
              )
              .catch(() => undefined)
          }
        >
          Submit payment
        </Button>
      </Stack>
      <Sonner richColors />
    </>
  );
}
```

## API


### [#](#sonner)Sonner



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |



### [#](#toast)toast



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |

