Sonner

An opinionated toast component for React.

README

https://user-images.githubusercontent.com/36730035/220868994-f0c92862-7e7d-487c-ab3a-540e7b48ab4a.mp4

Introduction


Sonner is an opinionated toast component for React. It's customizable, but styled by default. Comes with a swipe to dismiss animation.

Usage


To start using the library, install it in your project:

  1. ```bash
  2. npm install sonner
  3. ```

Add `` to your app, it will be the place where all your toasts will be rendered.
After that you can use toast() from anywhere in your app.

  1. ```jsx
  2. import { Toaster, toast } from 'sonner';

  3. // ...

  4. function App() {
  5.   return (
  6.     <div>
  7.       <Toaster />
  8.       <button onClick={() => toast('My first toast')}>Give me a toast</button>
  9.     </div>
  10.   );
  11. }
  12. ```

Types


Default


Most basic toast. You can customize it (and any other type) by passing an options object as the second argument.

  1. ```jsx
  2. toast('Event has been created');
  3. ```

With custom icon and description:

  1. ```jsx
  2. toast('Event has been created', {
  3.   description: 'Monday, January 3rd at 6:00pm',
  4.   icon: <MyIcon />,
  5. });
  6. ```

Success


Renders a checkmark icon in front of the message.

  1. ```jsx
  2. toast.success('Event has been created');
  3. ```

Error


Renders an error icon in front of the message.

  1. ```jsx
  2. toast.error('Event has not been created');
  3. ```

Action


Renders a button.

  1. ```jsx
  2. toast('Event has been created', {
  3.   action: {
  4.     label: 'Undo',
  5.     onClick: () => console.log('Undo'),
  6.   },
  7. });
  8. ```

Promise


Starts in a loading state and will update automatically after the promise resolves or fails.

  1. ```jsx
  2. toast.promise(() => new Promise((resolve) => setTimeout(resolve, 2000)), {
  3.   loading: 'Loading',
  4.   success: 'Success',
  5.   error: 'Error',
  6. });
  7. ```

You can pass a function to the success/error messages to incorporate the result/error of the promise.

  1. ```jsx
  2. toast.promise(promise, {
  3.   loading: 'Loading...',
  4.   success: (data) => {
  5.     return `${data.name} has been added!`;
  6.   },
  7.   error: 'Error',
  8. });
  9. ```

Custom JSX


You can pass jsx as the first argument instead of a string to render custom jsx while maintaining default styling. You can use the headless version below for a custom, unstyled toast.

  1. ```jsx
  2. toast(<div>A custom toast with default styling</div>);
  3. ```

Customization


Headless


You can use toast.custom to render an unstyled toast with custom jsx while maintaining the functionality.

  1. ```jsx
  2. toast.custom((t) => (
  3.   <div>
  4.     This is a custom component <button onClick={() => toast.dismiss(t)}>close</button>
  5.   </div>
  6. ));
  7. ```

Theme


You can change the theme using the theme prop. Default theme is light.

  1. ```jsx
  2. <Toaster theme="dark" />
  3. ```

Position


You can change the position through the `position` prop on the `` component. Default is `bottom-right`.

  1. ```jsx
  2. // Available positions
  3. // top-left, top-center, top-right, bottom-left, bottom-center, bottom-right

  4. <Toaster position="top-center" />
  5. ```

Expanded


Toasts can also be expanded by default through the expand prop. You can also change the amount of visible toasts which is 3 by default.

  1. ```jsx
  2. <Toaster expand visibleToasts={9} />
  3. ```

Styling for all toasts


You can style your toasts globally with the toastOptions prop in the Toaster component.

  1. ```jsx
  2. <Toaster
  3.   toastOptions={{ style: { background: 'red' }, className: 'my-toast', descriptionClassName: 'my-toast-description' }}
  4. />
  5. ```

Styling for individual toast


  1. ```jsx
  2. toast('Event has been created', {
  3.   style: {
  4.     background: 'red',
  5.   },
  6.   className: 'my-toast',
  7.   descriptionClassName: 'my-toast-description',
  8. });
  9. ```

Close button


Add a close button to all toasts that shows on hover by adding the closeButton prop.

  1. ```jsx
  2. <Toaster closeButton />
  3. ```

Rich colors


You can make error and success state more colorful by adding the richColors prop.

  1. ```jsx
  2. <Toaster richColors />
  3. ```

Custom offset


Offset from the edges of the screen.

  1. ```jsx
  2. <Toaster offset="80px" />
  3. ```

Programmatically remove toast


To remove a toast programmatically use toast.dismiss(id).

  1. ```jsx
  2. const toastId = toast('Event has been created');

  3. toast.dismiss(toastId);
  4. ```

Keyboard focus


You can focus on the toast area by pressing ⌥/alt + T. You can override it by providing an array of event.code values for each key.

  1. ```jsx
  2. <Toaster hotkey={['KeyC']} />
  3. ```