x-toaster

x-toaster is a customizable toast notification library for displaying brief messages to users. It has zero dependencies, is lightweight (1.4k min+gzip), and highly customizable.

Quick Start

Put a toast template on your page with x-toast-template and include slots for the message, title (optional), and close button (optional):

<template x-toast-template>
  <div>
    <div x-title></div>
    <button x-close>Close</button>
    <div x-message></div>
  </div>
</template>

Style x-toaster and x-toast:

x-toaster {
  position: fixed;
  top: 1rem;
  left: 50%;
}
x-toast {
  position: absolute;
  width: max-content;
  transform: translateX(-50%);
}

Use the library:

import * as toaster from 'x-toaster'
toaster.show('Hello, world!')

Advanced Usage

Toast Template

x-toaster clones the content of a template element (by default, with the x-toast-template attribute) for each toast that is shown.

• The required element with x-message will have its text content set to the toast message.
• The element with x-title will have its text content to set to the toast title (or left empty, if no title is specified).
• All elements with x-close will be wired up to close the toast when clicked.
  • You can put x-close on the toast itself to make the entire toast clickable.

JavaScript API

init

export function init(options?: ToasterOptions): Toaster | null

init initializes a new toaster instance with the specified options.

If you don't need to change the defaults, calling init is optional. It will automatically be called when you show your first toast.

Available options:

• toasterTarget: a selector for the element to which the toaster will be appended (default: "body")
• templateSelector: a selector for the toast template element (default: "[x-toast-template]")
• removeDelay: how long to keep toasts in the DOM after they are marked hidden, in milliseconds, useful for animations (default: 0)
• reverse: whether to display new toasts at the top. When your toaster is at the top of the page, set reverse to true, and when it's at the bottom, set it to false (default: false)
• gap: spacing between toasts, in pixels (default: 12)
• maxToasts: the maximum number of toasts to display at once; excess toasts will be hidden automatically (default: 5)

init returns null and logs errors to the console if there were issues with custom element registration or the toast template.

The returned toaster instance will be saved globally for you, so you don't need to keep a reference to it if you only plan to use a single toaster.

show

export function show(message: string): Toast | null
export function show(options: ToastOptions): Toast | null

show displays a toast with the specified message or options.

Available options:

• message (required): the message to display in the toast.
• title: the title of the toast (default: "")
• duration: how long to keep the toast visible, in milliseconds (default: 5000)
• class: CSS classes to apply to the toast, for customizing/categorization (default: "")
• template: a custom template element for this toast only (default: use the template from init())

The global show function uses the global toaster instance or initializes one if it doesn't exist yet. It returns null if there were issues with initialization. show also exists as an instance method on Toaster, which has the same purpose but will never return null.

Toaster

class Toaster extends HTMLElement {
  show(message: string): Toast
  show(options: ToastOptions): Toast
}

Toaster inherits from HTMLElement; all typical HTMLElement methods are available.

show(...) displays a toast with the specified message or options. See above for details.

Toast

class Toast extends HTMLElement {
  hide(): void
  extend(ms: number): void
}

Toast inherits from HTMLElement; all typical HTMLELement methods are available.

hide() hides the toast.

extend(ms: number) changes how long the toast will be visible. It will be hidden after now() + ms.

Styling Notes

For simplicity, x-toaster doesn't ship with any default styles. The bare minimum styles are provided in the quick start above, but you are encouraged to customize the appearance of your toasts to match your application's design.

At a minimum:

• x-toaster should be position: fixed and anchored to somewhere on the edge of the viewport using top/bottom and left/right.
  • Set reverse: true when using a top-anchored toaster to display toasts properly.
• x-toast should be position: absolute and have width: max-content or some max-width.
  • If your toaster is centered on the screen, you will need transform: translateX(-50%) to center the toasts.
  • If your toaster is anchored to the right edge, you will need transform: translateX(-100%) to keep the toasts inside the viewport.

Animations

x-toaster positions toasts using CSS transforms. x-toasts will be added to the DOM and then become :state(visible), which you can use to transition them in and out of view. For example:

x-toast {
  opacity: 0;
  transition: opacity 300ms ease, transform 300ms ease;
}

x-toast:state(visible) {
  opacity: 100%;

  @starting-style {
    opacity: 0;
  }
}

Make sure to set removeDelay in init() to the duration of your exit animation to keep the toast element in the document until the animation is complete.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on the GitHub repository.

License

x-toaster is licensed under the MIT License. See the LICENSE file for more information.