ngx-sonner

# ngx-sonner An opinionated toast component for Angular. Based on [emilkowalski](https://github.com/emilkowalski)'s React [implementation](https://sonner.emilkowal.ski/). ## Angular compatibility | ngx-sonner | @angular | |------------|----------| | 3.0.0 | ≥19.0.0 | | 2.0.0 | ≥18.0.0 | | 1.0.0 | ≥17.3.0 | ## Quick start Install it with your favorite package manager: ```bash npm i ngx-sonner # or yarn add ngx-sonner # or pnpm add ngx-sonner # or bun add ngx-sonner ``` Add `<ngx-sonner-toaster />` 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. ```ts import { toast, NgxSonnerToaster } from 'ngx-sonner'; @Component({ selector: 'app-root', imports: [NgxSonnerToaster], template: ` <ngx-sonner-toaster /> <button (click)="toast('My first toast')">Give me a toast</button> ` }) export class AppComponent { protected readonly toast = toast; } ``` ## Table of contents - [toast()](#toast) - [Creating toasts](#creating-toasts) - [Default](#default) - [Success](#success) - [Info](#info) - [Warning](#warning) - [Error](#error) - [Action](#action) - [Cancel](#cancel) - [Promise](#promise) - [Loading](#loading) - [Custom component](#custom-component) - [Headless](#headless) - [Dynamic position](#dynamic-position) - [Other](#other) - [Updating a toast](#updating-a-toast) - [On Close Callback](#on-close-callback) - [Dismissing toasts programmatically](#dismissing-toasts-programmatically) - [Toaster](#toaster) - [Theme](#theme) - [Position](#position) - [Expand](#expand) - [Custom Icons](#custom-icons) - [Close button](#close-button) - [Rich colors](#rich-colors) - [Custom offset](#custom-offset) - [Duration](#duration) - [Keyboard focus](#keyboard-focus) - [Styling](#styling) - [TailwindCSS](#tailwind-css) ## toast() Use it to render a toast. You can call it from anywhere, even outside of React. ### Creating toasts #### Default Most basic toast. You can customize it (and any other type) by passing an options object as the second argument. ```ts toast('Event has been created'); ``` With custom icon and description: ```ts toast('Event has been created', { description: 'Monday, January 3rd at 6:00pm', icon: IconComponent }); ``` #### Success Renders a checkmark icon in front of the message. ```ts toast.success('Event has been created'); ``` #### Info Renders a question mark icon in front of the message. ```ts toast.info('Event has new information'); ``` #### Warning Renders a warning icon in front of the message. ```ts toast.warning('Event has warning'); ``` #### Error Renders an error icon in front of the message. ```ts toast.error('Event has not been created'); ``` #### Action Renders a primary button, clicking it will close the toast and run the callback passed via `onClick`. You can prevent the toast from closing by calling `event.preventDefault()` in the onClick callback. ```ts toast('My action toast', { action: { label: 'Action', onClick: () => console.log('Action!') } }); ``` #### Cancel Renders a secondary button, clicking it will close the toast and run the callback passed via `onClick`. ```ts toast('My cancel toast', { cancel: { label: 'Cancel', onClick: () => console.log('Cancel!'), }, }); ``` #### Promise Starts in a loading state and will update automatically after the promise resolves or fails. ```ts toast.promise(() => new Promise((resolve) => setTimeout(resolve, 2000)), { loading: 'Loading', success: 'Success', error: 'Error' }); ``` You can pass a function to the success/error messages to incorporate the result/error of the promise. ```ts toast.promise(promise, { loading: 'Loading...', success: (data) => { return `${data.name} has been added!`; }, error: 'Error' }); ``` #### Loading Renders a toast with a loading spinner. Useful when you want to handle various states yourself instead of using a promise toast. ```ts toast.loading('Loading data'); ``` #### Custom Component You can pass a component as the first argument instead of a string to render custom component while maintaining default styling. ```ts toast(CustomComponent); ``` #### Headless You can use `toast.custom()` to render an unstyled toast with a custom component while maintaining the functionality. ```ts @Component({ selector: 'app-custom', template: ` <div> This is a custom component <button (click)="toastClick()">close</button> </div> ` }) export class CustomComponent { toastClick() { console.log('Hello world!'); } } ``` ```ts import { CustomComponent } from './custom.component'; toast.custom(CustomComponent); ``` #### Dynamic position You can change the position of the toast dynamically by passing a position prop to the toast function. It will not affect the positioning of other toasts. ```ts // Available positions: // top-left, top-center, top-right, bottom-left, bottom-center, bottom-right toast('Hello World', { position: 'top-center', }); ``` ### Other #### Updating a toast You can update a toast by using the `toast` function and passing it the id of the toast you want to update, the rest stays the same. ```ts const toastId = toast('Sonner'); toast.success('Toast has been updated', { id: toastId }); ``` #### On Close Callback You can pass `onDismiss` and `onAutoClose` callbacks to each toast. `onDismiss` gets fired when either the close button gets clicked or the toast is swiped. `onAutoClose` fires when the toast disappears automatically after it's timeout (duration prop). ```ts 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`), }); ``` #### Dismissing toasts programmatically To remove a toast programmatically use `toast.dismiss(id)`. The `toast()` function return the id of the toast. ```ts const toastId = toast('Event has been created'); toast.dismiss(toastId); ``` You can also dismiss all toasts at once by calling `toast.dismiss()` without an id. ```ts toast.dismiss(); ``` ## Toaster This component renders all the toasts, you can place it anywhere in your app. ### Theme You can change the theme using the `theme` prop. Default theme is light. ```html <ngx-sonner-toaster theme="dark" /> ``` ### Position You can change the position through the `position` prop on the `<ngx-sonner-toaster />` component. Default is `bottom-right`. ```html   <ngx-sonner-toaster position="top-center" /> ``` ### Expand 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. ```html <ngx-sonner-toaster expand visibleToasts="9" /> ``` ### Custom icons You can change the default icons by providing your icons inside the toaster component. ```html <ngx-sonner-toaster> <custom-loading-icon loading-icon/> <custom-success-icon success-icon /> <custom-error-icon error-icon /> <custom-info-icon info-icon /> <custom-warning-icon warning-icon /> </ngx-sonner-toaster> ``` ### Close button Add a close button to all toasts that shows on hover by adding the `closeButton` prop. ```html <ngx-sonner-toaster closeButton /> ``` ### Rich colors You can make error and success state more colorful by adding the `richColors` prop. ```html <ngx-sonner-toaster richColors /> ``` ### Custom offset Offset from the edges of the screen. ```html <ngx-sonner-toaster offset="80px" /> ``` ### Duration You can change the duration of each toast by using the `duration` property, or change the duration of all toasts like this: ```html <ngx-sonner-toaster duration="10000" /> ``` ```ts toast('Event has been created', { duration: 10000 }); // Persisent toast toast('Event has been created', { duration: Number.POSITIVE_INFINITY }); ``` ### 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. ```html <ngx-sonner-toaster [hotKey]="['KeyC']" /> ``` ## Styling Styling can be done globally via `toastOptions`, this way every toast will have the same styling. ```html <ngx-sonner-toaster [toastOptions]="{ style: { background: 'red' }, className: 'my-toast', }" /> ``` You can also use the same props when calling `toast` to style a specific toast. ```ts toast('Event has been created', { style: 'background: red;', class: 'my-toast', descriptionClass: 'my-toast-description' }); ``` ### Tailwind CSS The preferred way to style the toasts with tailwind is by using the `unstyled` prop. That will give you an unstyled toast which you can then style with tailwind. ```html <ngx-sonner-toaster [toastOptions]="{ unstyled: true, classes: { toast: 'bg-blue-400', title: 'text-red-400', description: 'text-red-400', actionButton: 'bg-zinc-400', cancelButton: 'bg-orange-400', closeButton: 'bg-lime-400', } }" /> ``` You can do the same when calling `toast()`. ```ts toast('Hello World', { unstyled: true, classes: { toast: 'bg-blue-400', title: 'text-red-400 text-2xl', description: 'text-red-400', actionButton: 'bg-zinc-400', cancelButton: 'bg-orange-400', closeButton: 'bg-lime-400', }, }) ``` Styling per toast type is also possible. ```html <ngx-sonner-toaster [toastOptions]="{ unstyled: true, classes: { error: 'bg-red-400', success: 'text-green-400', warning: 'text-yellow-400', info: 'bg-blue-400', } }" /> ``` ## License [MIT](https://github.com/tutkli/ngx-sonner/blob/master/LICENSE)