Sonner

https://sonner.emilkowal.ski/
Admin
Sonner is an opinionated toast component for React, allowing developers to render customizable toast...
Tokens:7,012
Snippets:84
Trust Score:8.7
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install Sonner with pnpm

Source: https://sonner.emilkowal.ski/getting-started

Install the sonner package from the command line using pnpm.

```bash
pnpm i sonner
```

--------------------------------

### Basic usage of Toaster and toast

Source: https://sonner.emilkowal.ski/

Render the Toaster component in the root of your app and trigger a toast with the toast function. This example shows the minimal setup required.

```jsx
import { Toaster, toast } from 'sonner'

// ...

function App() {
  return (
    <div>
      <Toaster />
      <button onClick={() => toast('My first toast')}>
        Give me a toast
      </button>
    </div>
  )
}
```

--------------------------------

### Install Sonner with npm

Source: https://sonner.emilkowal.ski/

Install the Sonner package using npm.

```bash
npm install sonner
```

--------------------------------

### Headless / TailwindCSS: Render toast

Source: https://sonner.emilkowal.ski/styling

The headless approach removes default styles and gives full control of the JSX. The example shows a custom toast function that can be abstracted to accept different props.

```jsx
// The code for the headless approach is not fully visible in the source, but the example shows a custom toast function.
// The source mentions 'Render toast' and 'You can also abstract the toast() function like in the example above'.
// Since the actual code is not displayed, this snippet is excluded.
```

--------------------------------

### Rich colors and success toast

Source: https://sonner.emilkowal.ski/

Use the richColors prop on the Toaster component to enable rich colors for toasts. This example shows a success toast and the Toaster with richColors.

```jsx
toast.success('Event has been created')

// ...

<Toaster richColors  />
```

--------------------------------

### useSonner hook to get visible toasts

Source: https://sonner.emilkowal.ski/other

Use the useSonner hook to retrieve all visible toasts. The toasts array contains each toast's id.

```javascript
const { toasts } = useSonner();
const toastsAmount = toasts.length;
```

--------------------------------

### Get active toasts outside React

Source: https://sonner.emilkowal.ski/other

Use toast.getActiveToasts() to get an array of all toasts outside of React.

```javascript
const toasts = toast.getActiveToasts();
```

--------------------------------

### toast(message, options?)

Source: https://sonner.emilkowal.ski/toast

Renders a toast with a string title and optional options object. Options override the defaults set on the Toaster component.

```APIDOC
## toast(message, options?)

### Description
Renders a toast with a string title and optional options object. Options override the defaults set on the Toaster component.

### Method
Function call

### Signature
`toast(message: ReactNode, options?: ToastOptions)`

### Parameters
- **message** (ReactNode) - Required - The title of the toast. Can be a string or JSX for custom toasts.
- **options** (object) - Optional - Configuration options for the toast. See API Reference for available props.

### Options (from API Reference)
- **description** (ReactNode) - Optional - Additional description content.
- **closeButton** (boolean) - Optional - Default `false`. Shows a close button.
- **invert** (boolean) - Optional - Default `false`. Inverts the toast colors.
- **duration** (number) - Optional - Default `4000`. Duration in milliseconds before auto-close.
- **position** (string) - Optional - Default `bottom-right`. Position of the toast.
- **dismissible** (boolean) - Optional - Default `true`. Allows dismissing the toast.
- **icon** (ReactNode) - Optional - Custom icon.
- **action** (ReactNode) - Optional - Renders a primary button. Clicking it closes the toast and runs the `onClick` callback. Can be JSX.
- **cancel** (ReactNode) - Optional - Renders a secondary button. Clicking it closes the toast and runs the `onClick` callback. Can be JSX.
- **id** (string) - Optional - Unique identifier for the toast.
- **testId** (string) - Optional - Test identifier.
- **toasterId** (string) - Optional - Identifier for the toaster instance.
- **onDismiss** (function) - Optional - Callback when toast is dismissed.
- **onAutoClose** (function) - Optional - Callback when toast auto-closes.
- **containerAriaLabel** (string) - Optional - Default `Notifications`. ARIA label for the toast container.
- **actionButtonStyle** (object) - Optional - Default `{}`. Style for the action button.
- **cancelButtonStyle** (object) - Optional - Default `{}`. Style for the cancel button.

### Usage Examples

#### Basic
```js
toast('My toast');
```

#### With options
```js
toast('My toast', {
  description: 'This is a description',
  duration: 5000,
});
```

#### Success
```js
toast.success('Success message');
```

#### Error
```js
toast.error('Error message');
```

#### Action
```js
toast('My action toast', {
  action: {
    label: 'Action',
    onClick: () => console.log('Action!'),
  },
});
```

#### Cancel
```js
toast('My cancel toast', {
  cancel: {
    label: 'Cancel',
    onClick: () => console.log('Cancel!'),
  },
});
```

#### Promise
```js
const promise = fetchData();
toast.promise(promise, {
  loading: 'Loading...',
  success: (data) => `Success: ${data}`,
  error: (err) => `Error: ${err}`,
});
```

#### Loading
```js
toast.loading('Loading...');
```

#### Custom
```js
toast(<div>Custom content</div>);
```

#### Headless
```js
toast.custom((t) => <div>Custom headless toast</div>);
```

### Response
No return value documented.
```

--------------------------------

### Import Sonner styles for Astro

Source: https://sonner.emilkowal.ski/other

If you use Astro with view transitions or run into other Sonner issues with Astro, import Sonner's styles into a layout file.

```javascript
import 'sonner/dist/styles.css';
```

--------------------------------

### Render custom elements in toast

Source: https://sonner.emilkowal.ski/other

Pass a function instead of a string to render custom elements like <a /> or custom components in the title or description.

```javascript
toast(
  () => (
    <>
      View{' '}
      <a href="https://animations.dev/" target="_blank">
        Animation on the Web
      </a>
    </>
  ),
  {
    description: () => <button>This is a button element!</button>,
  }
);
```

--------------------------------

### Render a toast with toast()

Source: https://sonner.emilkowal.ski/getting-started

Use the toast function to display a toast when a button is clicked. For all options, view the toast page.

```tsx
import { toast } from 'sonner';
 
function MyToast() {
  return <button onClick={() => toast('Toast')}>Render Toast</button>;
}
```

--------------------------------

### Using unstyled prop for full control

Source: https://sonner.emilkowal.ski/styling

The unstyled prop removes all styles, allowing you to apply your own without !important. This is useful for a few changes, but headless provides more control.

```jsx
toast('Hello World', {
  unstyled: true,
  classNames: {
    toast: 'toast',
    title: 'title',
    description: 'description',
    actionButton: 'action-button',
    cancelButton: 'cancel-button',
    closeButton: 'close-button',
  },
});
```

--------------------------------

### Render toast with JSX action

Source: https://sonner.emilkowal.ski/toast

Renders a toast with a JSX element as the action button. Clicking the button logs 'Action!' to the console.

```jsx
toast('My action toast', {
  action: <Button onClick={() => console.log('Action!')}>Action</Button>,
});
```

--------------------------------

### Customizing offsets with offset and mobileOffset

Source: https://sonner.emilkowal.ski/toaster

Customizes offsets using the offset and mobileOffset props. Default desktop offset is 32px, default mobile offset is 16px. mobileOffset applies when screen width is less than 600px.

```jsx
// all sides will have 16px offset
<Toaster offset={16} />
 
// all sides will have 10vh offset
<Toaster offset="10vh" />
 
// 24px from the bottom, 16px from the right and left
<Toaster offset={{ bottom: '24px', right: "16px", left: "16px" }} />
 
// mobile offset will be 16px from the bottom, default values for the rest
<Toaster mobileOffset={{ bottom: '16px' }} />
```

--------------------------------

### Global styles with toastOptions

Source: https://sonner.emilkowal.ski/styling

Use the toastOptions prop on the Toaster component to apply the same styling to every toast, such as changing the background color.

```jsx
<Toaster
  toastOptions={{
    style: {
      background: 'red',
    },
  }}
/>
```

--------------------------------

### Style a specific toast with toast()

Source: https://sonner.emilkowal.ski/styling

Use the same style props when calling the toast function to style a specific toast.

```jsx
toast('Hello World', {
  style: {
    background: 'red',
  },
});
```

--------------------------------

### Dynamic theme with next-themes

Source: https://sonner.emilkowal.ski/toaster

Makes the toaster's theme adapt to the app's theme by passing a theme prop from a theme provider like next-themes. Uses the resolvedTheme from useTheme and casts it to ToasterProps['theme'].

```tsx
'use client';
 
import { Toaster as SonnerToaster, type ToasterProps } from 'sonner';
import { useTheme } from 'next-themes';
 
export function Toaster() {
  const { resolvedTheme } = useTheme();
 
  return <SonnerToaster theme={resolvedTheme as ToasterProps['theme']} />;
}
```

--------------------------------

### Multiple Toasters with toasterId

Source: https://sonner.emilkowal.ski/toaster

Renders multiple toasters for clear separation and points toasts to a specific toaster using the toasterId option in the toast function.

```jsx
<Toaster id="global" position="top-right" />
<Toaster id="canvas" position="bottom-left" />
 
<button onClick={() => toast('Global toast', { toasterId: 'global' })}>
  Show in Global Toaster
</button>
<button onClick={() => toast('Canvas toast', { toasterId: 'canvas' })}>
  Show in Canvas Toaster
</button>
```

--------------------------------

### Changing default icons with icons prop

Source: https://sonner.emilkowal.ski/styling

Use the icons prop on the Toaster to change the default icons for success, info, warning, error, and loading toasts.

```jsx
<Toaster
  icons={{
    success: <SuccessIcon />,
    info: <InfoIcon />,
    warning: <WarningIcon />,
    error: <ErrorIcon />,
    loading: <LoadingIcon />,
  }}
/>
```

--------------------------------

### Persist toast with duration Infinity

Source: https://sonner.emilkowal.ski/other

Set duration to Infinity to make a toast never disappear automatically.

```javascript
toast('This toast will stay on screen forever', {
  duration: Infinity,
});
```

--------------------------------

### Styling with Tailwind and !important

Source: https://sonner.emilkowal.ski/styling

When using Tailwind, mark classes as !important to ensure they are applied correctly.

```jsx
<Toaster
  toastOptions={{
    classNames: {
      description: '!text-red-900',
    },
  }}
/>
```

--------------------------------

### Expand and visibleToasts props

Source: https://sonner.emilkowal.ski/toaster

Sets the expand prop to true to make toasts expand by default, and visibleToasts to control how many toasts are visible. The default visible count is 3.

```jsx
// 9 toasts will be visible instead of the default, which is 3.
<Toaster expand visibleToasts={9} />
```

--------------------------------

### Add Toaster to layout.tsx

Source: https://sonner.emilkowal.ski/getting-started

Place the Toaster component in your root layout. It can be placed anywhere, even in server components such as layout.tsx.

```tsx
import { Toaster } from 'sonner';
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <Toaster />
      </body>
    </html>
  );
}
```

--------------------------------

### Change toast type with toast.success

Source: https://sonner.emilkowal.ski/other

To change the type of an existing toast, call toast.success(), toast.error(), etc., passing the same id.

```javascript
toast.success('Toast has been updated', {
  id: toastId,
});
```

--------------------------------

### Styling specific elements with classNames

Source: https://sonner.emilkowal.ski/styling

Apply classes to each element within the toast using the classNames option. You need to use !important to override default styles.

```jsx
<Toaster
  toastOptions={{
    classNames: {
      toast: 'toast',
      title: 'title',
      description: 'description',
      actionButton: 'action-button',
      cancelButton: 'cancel-button',
      closeButton: 'close-button',
    },
  }}
/>
```

--------------------------------

### Render toast with JSX cancel

Source: https://sonner.emilkowal.ski/toast

Renders a toast with a JSX element as the cancel button. Clicking the button logs 'Cancel!' to the console.

```jsx
toast('My cancel toast', {
  cancel: <Button onClick={() => console.log('Cancel!')}>Cancel</Button>,
});
```

--------------------------------

### Remove all toasts with useSonner

Source: https://sonner.emilkowal.ski/other

Iterate over the toasts from useSonner and dismiss each by its id to delete all toasts at once.

```javascript
function removeAllToasts() {
  toasts.forEach((t) => toast.dismiss(t.id));
}
```

--------------------------------

### Set an icon for a specific toast

Source: https://sonner.emilkowal.ski/styling

Use the icon option when calling toast to set a custom icon for that specific toast.

```jsx
toast('Hello World', {
  icon: <Icon />,
});
```

--------------------------------

### Position prop

Source: https://sonner.emilkowal.ski/toaster

Changes the position where all toasts are rendered. Available positions are top-left, top-center, top-right, bottom-left, bottom-center, bottom-right.

```jsx
// Available positions:
// top-left, top-center, top-right, bottom-left, bottom-center, bottom-right
<Toaster position="top-center" />
```

--------------------------------

### Default toast type

Source: https://sonner.emilkowal.ski/

Call the toast function with a message to display a default toast.

```jsx
toast('Event has been created')
```

--------------------------------

### Control visible toasts with expand prop

Source: https://sonner.emilkowal.ski/

Use the expand prop on the Toaster component to change the amount of toasts visible. The default value is false.

```jsx
<Toaster expand={false} />
```

--------------------------------

### onDismiss and onAutoClose callbacks

Source: https://sonner.emilkowal.ski/other

Pass onDismiss and onAutoClose callbacks to a toast. onDismiss fires when the close button is clicked or the toast is swiped; onAutoClose fires when the toast disappears after its timeout (duration prop).

```javascript
toast('Event has been created', {
  onDismiss: (t) => console.log(`Toast with id ${t.id} has been dismissed`),
  onAutoClose: (t) => console.log(`Toast with id ${t.id} has been closed automatically`),
});
```

--------------------------------

### Update a toast by id

Source: https://sonner.emilkowal.ski/other

Use the toast function with the id of an existing toast to update only the properties you specify. The rest of the toast remains unchanged.

```javascript
const toastId = toast('Sonner');
 
/** Only title gets updated, the rest stays the same */
toast('Toast has been updated', {
  id: toastId,
});
```

--------------------------------

### Dismiss all toasts

Source: https://sonner.emilkowal.ski/other

Call toast.dismiss() without an id to dismiss all toasts at once.

```javascript
toast.dismiss();
```

--------------------------------

### Toaster Component

Source: https://sonner.emilkowal.ski/toaster

The Toaster component renders all toasts. It can be customized with various props to control expand behavior, position, offsets, theme, and more.

```APIDOC
## Toaster Component

### Description
The Toaster component renders all toasts. It can be placed anywhere in your app and customized with various props.

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `string` | `light` | The theme of the toaster. |
| `richColors` | `boolean` | `false` | Enables rich colors for toasts. |
| `expand` | `boolean` | `false` | When true, toasts expand on hover. |
| `visibleToasts` | `number` | `3` | Number of toasts visible. |
| `id` | `string` | `-` | Unique identifier for the toaster. |
| `position` | `string` | `bottom-right` | Position of the toaster. Available: top-left, top-center, top-right, bottom-left, bottom-center, bottom-right. |
| `closeButton` | `boolean` | `false` | Shows a close button on toasts. |
| `offset` | `string \| number \| object` | `32px` | Offset from the edges. Can be a number, string, or object with top, bottom, left, right. |
| `mobileOffset` | `string \| number \| object` | `16px` | Offset for mobile screens (width < 600px). |
| `swipeDirections` | `[]` | `based on position` | Swipe directions for dismissing toasts. |
| `dir` | `string` | `ltr` | Text direction. |
| `hotkey` | `string` | `⌥/alt + T` | Hotkey to focus the toaster. |
| `invert` | `boolean` | `false` | Inverts the toaster colors. |
| `toastOptions` | `object` | `4000` | Options for toasts. |
| `gap` | `number` | `14` | Gap between toasts. |
| `icons` | `object` | `-` | Custom icons for toasts. |

### Examples

#### Expand
```jsx
// 9 toasts will be visible instead of the default, which is 3.
<Toaster expand visibleToasts={9} />
```

#### Position
```jsx
// Available positions:
// top-left, top-center, top-right, bottom-left, bottom-center, bottom-right
<Toaster position="top-center" />
```

#### Multiple Toasters
```jsx
<Toaster id="global" position="top-right" />
<Toaster id="canvas" position="bottom-left" />
 
<button onClick={() => toast('Global toast', { toasterId: 'global' })}>
  Show in Global Toaster
</button>
<button onClick={() => toast('Canvas toast', { toasterId: 'canvas' })}>
  Show in Canvas Toaster
</button>
```

#### Customizing offsets
```jsx
// all sides will have 16px offset
<Toaster offset={16} />
 
// all sides will have 10vh offset
<Toaster offset="10vh" />
 
// 24px from the bottom, 16px from the right and left
<Toaster offset={{ bottom: '24px', right: "16px", left: "16px" }} />
 
// mobile offset will be 16px from the bottom, default values for the rest
<Toaster mobileOffset={{ bottom: '16px' }} />
```

#### Dynamic theme
```jsx
'use client';
 
import { Toaster as SonnerToaster, type ToasterProps } from 'sonner';
import { useTheme } from 'next-themes';
 
export function Toaster() {
  const { resolvedTheme } = useTheme();
 
  return <SonnerToaster theme={resolvedTheme as ToasterProps['theme']} />;
}
```
```

--------------------------------

### Removing icons for specific or all toasts

Source: https://sonner.emilkowal.ski/styling

Pass null to the icon option to remove the icon for a specific toast, or set the icon to null in the Toaster's icons prop to remove it for all toasts of that type.

```jsx
// Removing the icon for a specific success toast
toast.success('Hello World', {
  icon: null,
});
 
// Removing the icon for all success toasts
<Toaster
  icons={{
    success: null,
  }}
/>
```

--------------------------------

### Set Toaster position

Source: https://sonner.emilkowal.ski/

Use the position prop on the Toaster component to control where toasts appear. Swipe direction changes depending on the position.

```jsx
<Toaster position="bottom-right" />
```

--------------------------------

### Dismiss a toast programmatically

Source: https://sonner.emilkowal.ski/other

Use toast.dismiss(id) to remove a specific toast. The toast() function returns the id of the toast.

```javascript
const toastId = toast('Event has been created');
 
toast.dismiss(toastId);
```

--------------------------------

### Add Sonner styles to shadow DOM

Source: https://sonner.emilkowal.ski/other

Sonner's styles are inserted into the document's head, so they are not available in shadow DOM. Manually append the style elements that contain '[data-sonner-toaster]' to the shadow root.

```javascript
document.head.querySelectorAll('style').forEach((styleEl) => {
  if (styleEl.textContent?.includes('[data-sonner-toaster]')) {
    shadow.append(styleEl);
  }
});
```
Tokens:
Raw