Guide · Open source

How to use toastr: install, show toasts and customize them

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Toastr is a JavaScript library that shows short, non-blocking notification messages, called toasts, on a web page. It is built on jQuery, so it fits best in sites that already use it. This guide covers installing toastr, showing your first toast, and changing common options such as timing, close buttons and duplicate handling.

toastrCodeSeven/toastr · ★ 12.1k · MIT Install options & downloads

Quick start

1Install or link toastr. Install toastr with npm install --save toastr or yarn add toastr, or link the CDN files. Make sure jQuery is loaded.
2Link the stylesheet. Add toastr.css to the page with a link tag in the head.
3Link the script. Add toastr.js after jQuery with a script tag.
4Show a toast. Call toastr.info, toastr.success, toastr.warning or toastr.error with a message and an optional title.
5Set global options. Assign values to toastr.options, such as timeOut, preventDuplicates or closeButton.
6Add callbacks if needed. Use onShown, onHidden, onclick or onCloseClick to run code when toasts change state.

What you need before you install toastr

The README states that jQuery is required. Toastr is a jQuery-based library, so your page needs jQuery loaded before toastr.

Toastr is distributed through several channels, including npm, yarn, Bower, NuGet and a CDN. The README also documents a Ruby on Rails gem, toastr-rails.

jQuery must be available on the page
Use npm or yarn for a package-manager install, or link the files from a CDN

Install toastr with npm or yarn

If your project uses npm, install toastr from the command line with the command below. The README also lists yarn as an option.

Toastr is hosted at cdnjs and jsdelivr. The README lists minified CSS and JavaScript files at cdnjs if you prefer to link files directly instead of installing a package.

npm: install with the save flag
yarn: add the package

npm install --save toastr

Show your first toast

Quick start has three steps. First, link the stylesheet toastr.css. Second, link toastr.js. Third, call one of the four display functions: info, success, warning or error.

You can pass a message alone, or a message and a title. The title is optional.

Link toastr.css in the page head
Link toastr.js after jQuery
Call toastr.info, toastr.success, toastr.warning or toastr.error

// Display an info toast with no title
toastr.info('Are you the 6 fingered man?')

// Display a success toast, with a title
toastr.success('Have fun storming the castle!', 'Miracle Max Says')

Change toast behaviour with options

Toastr reads its settings from toastr.options. You can set them once globally, or pass options to a single call to override the global setting for that toast.

Timing is controlled by timeOut, which is how long a toast shows without user interaction, and extendedTimeOut, which is how long it shows after the user hovers over it. Setting both to 0 keeps the toast until the user closes it. Duplicate messages can be blocked with preventDuplicates, which matches duplicates by message content.

timeOut: time before the toast hides without interaction
extendedTimeOut: time after hovering
timeOut and extendedTimeOut set to 0: toast stays until selected
preventDuplicates: stops identical messages from stacking
progressBar: shows how long before a toast expires
rtl: flips the display for right-to-left languages
escapeHtml: escapes HTML in the title and message
newestOnTop: set to false to show newest at the bottom

toastr.options.timeOut = 30;
toastr.options.extendedTimeOut = 60;
toastr.options.preventDuplicates = true;
toastr.options.progressBar = true;

// Override global options for one toast
toastr.success('We do have the Kapua suite available.', 'Turtle Bay Resort', {timeOut: 5000})

Add a close button and callbacks

A close button is off by default. Enable it with closeButton, and you can override its HTML with closeHtml. The README also describes closeMethod, closeDuration and closeEasing for the close button's hide animation.

Callbacks let your code react when a toast is shown, hidden, clicked or closed with the close button. The README lists onShown, onHidden, onclick and onCloseClick.

closeButton: enables the close button
closeHtml: custom HTML for the close button
onShown, onHidden, onclick, onCloseClick: callbacks

toastr.options.closeButton = true;

toastr.options.onShown = function() { console.log('hello'); }
toastr.options.onHidden = function() { console.log('goodbye'); }

Clear toasts and customize animations

toastr.remove() removes current toasts immediately without animation. toastr.clear() removes them using animation.

Toastr supplies default animations. You can override them with showMethod, hideMethod, showEasing and hideEasing. The README notes that fadeIn/fadeOut, slideDown/slideUp and show/hide are built into jQuery, and that easings such as swing and linear are built in, with others available through the jQuery Easing plugin.

The README lists deprecated animation options. Replace options.fadeIn with options.showDuration, options.onFadeIn with options.onShown, options.fadeOut with options.hideDuration, and options.onFadeOut with options.onHidden.

toastr.remove(): immediate removal
toastr.clear(): removal with animation
Deprecated: fadeIn, onFadeIn, fadeOut, onFadeOut

toastr.options.showMethod = 'slideDown';
toastr.options.hideMethod = 'slideUp';
toastr.clear();
toastr.remove();

What people use it for

Confirming that a form was saved on a jQuery-based admin page
Showing an error message when a request fails, without blocking the user
Keeping an important warning on screen until the user closes it by setting timeOut to 0
Preventing the same message from stacking when a user repeats an action with preventDuplicates
Displaying notifications in right-to-left languages with the rtl option

Frequently asked questions

Does toastr require jQuery?

Yes. The README states that jQuery is required. Load jQuery on the page before you load toastr.js.

How do I install toastr?

The README gives npm install --save toastr and yarn add toastr. You can also use Bower, NuGet, a CDN or the Ruby on Rails gem toastr-rails.

Is toastr free to use?

The README says toastr is under the MIT license. Check the LICENSE file in the repository for the full terms.

How do I make a toast stay on screen until it is closed?

Set toastr.options.timeOut and toastr.options.extendedTimeOut to 0. The toast will persist until the user selects it or closes it.

How do I stop duplicate toasts?

Set toastr.options.preventDuplicates to true. Duplicates are matched to the previous toast based on their message content.

Is toastr still maintained, and what are alternatives?

Our analysis notes the last push was in February 2023, so check recent activity before you adopt it. Comparable projects include notifier.js, Notyf, iziToast and SweetAlert2.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Toastr suits web developers who already use jQuery and want simple, customizable on-screen notifications with a small API. Projects without jQuery, teams that need a recently updated library, or apps that need native system alerts should consider alternatives such as Notyf, iziToast, SweetAlert2 or notifier.js.

Install options & downloads