bnjmnrsh / toast

A utility for managing toast like UI notifications.

@bnjmnrsh/toast.js

A utility for managing toast-like UI notifications.

And here is a bare-bones CodePen demo: https://codepen.io/bnjmnrsh/pen/vYPyJXQ

Table of Contents

• Installation
• What's this about
• Usage
• Targeting
• Classes & IDs
• Methods
• Styling
• Note on a11y
• Licence

Installation ↑

Use npm to install the latest version of Toast.js from Github.

npm i https://github.com/bnjmnrsh/toast

A specific tag can be targeted by appending a hash and the tag name to the URL:

npm i https://github.com/bnjmnrsh/toast#v0.0.1

---

What's this about ↑

Toast.js is a flexible utility to create and manage browser toast-type notifications, with basic accessibility baked in. It offers a range of configuration options, including custom classes, autohide, and more.

---

Usage ↑

import {Toast} from '@bnjmnrsh/toast';
const toaster = new Toast({"target":"body", "className":"toast"}); // defaults
toaster.create('Hi I\'m a toast!', 0, false, false, [], false);

See notes on Toast Instantiation.

---

Targeting ↑

Each Toast() instance can be attached to a different target parent node, allowing you to use multiple areas of your UI to display notifications. Further, subsequent notifications can be prepended or appended within the target. See notes on Toast Instantiation, Toast.create() for details.

const toaster = new Toast({"target": "#my-target"});

---

Classes & IDs ↑

Toast.js provides a few ways to target notifications on the DOM:

Custom toast classes

When creating new toasts, you can optionally add an array of classes, allowing for different types of message styling, such as warnings.

data-toast-id

Toast() assigns a unique identifier to each notification on a data-toast-id attribute. You may optionally pass in your own ID instead when creating new notifications using Toast().create().

toaster.create("I'm a toast!",0, false, false, ['-is-warning', '-is-large'], 'awsome-toast-123321')

See Toast.create() for full details.

---

Methods ↑

new Toast() --> Toast object

Instantiate a new Toast. Accepts an optional object with target and className properties.

const toaster = new Toast({
  "target":"#my-target-el", // target El to attach toasts to, defaults to 'body'
  "className":"my-toast",   // base class for all toasts, defaults to 'toast'
 })

---

Toast.create(...) --> ID string

Trigger a new notification to be added to the DOM. Toast.create() returns the id assigned to the toast's data-toast-id attribute as a string.

toaster.create(
  message {string}, // toast message string
  autohide {int:0}, // autohide the toast after X millisecond
  dismissible {boolean:false}, // renders close button to dismiss notification
  prepend {boolean:true}, // false will append the toast to the end of any nodes in the target container.
  classes {array}, // An array of classes to add to the toast container
  id {string:false}, // Custom identifier assigned to `data-toast-id`, if empty toast generates its own id.
)

---

Toast.destroy() --> Toast object

Removes a toast notification from the DOM by targeting the id found on the toast's data-toast-id attribute.

  Toast.destroy(
    id{string}
  )

Usage:

const toaster = new Toast()
const myToast = toaster.create("I'm a toast!")
toaster.destroy(myToast)

---

Styling ↑

Toast.js doesn't ship with any CSS styles; below is a basic toast example:

.toast {
  display: flex;
  position: relative;
  flex-direction: row;
  align-items: center;
  justify-content: space-between;
  margin: 5px;
  padding: 5px;
  border: 1px solid;
  border-radius: 5px;
  background: lightgrey;
  color: #121111;
}
.toast .toast-close {
  display: inline-flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  width: 20px;
  height: 20px;
  border: 1px solid;
  border-radius: 100px;
  line-height: 1;
  text-align: center;
}

---

Notes on a11y ↑

There are a few minimum accessibility requirements that Toast.js implements. Firstly, all toast messages are given the aria role="alert" attribute. This role by itself, however, is not enough to make screen readers announce a notification, as this role only flags to screen readers that any content in this node should be announced as an alert once it detects a change. No announcement will be made if the DOM element and its content are added together. To get around this limitation, Toast.js first appends/prepends the notification to the DOM, and then a millisecond later, populates the toast message inside. This delay won't be noticed by users, but it is enough to trigger an announcement by screen readers¹.

While Toast.js puts in place a strong foundation of HTML and basic behaviour, the accessibility of any component is dependent on how it is styled and implemented. It's best to review your own implementation regularly to understand how it may be affecting your users.

Further Reading:

• W3C: Aria Authoring Practices: Alert
• W3C: Notifications and Feedback
• Inclusive Components: Notifications | Heydon Pickering

---

LICENCE ISC ↑

Copyright (c) 2022 Benjamin O. Rush (bnjmnrsh).

Footnotes

1. Credit here goes to Heydon Pickering, who is the first person I am aware of covering the technique in the book/website Inclusive Components. ↩

toast's Issues

sanitise string input for .create()

Consider sanitising string input for .create(), or add a warning to notes if we want to add markup. Simple sanitisation would be to create a <template> with js, set it's innerHTML to the string and then retrieve it again, at which point any entities will be encoded.

streamline api for .create()

Consider passing string as first param, and add options object as second param.
Would be breaking change.

toaster.create('hey, new toast!', {
          "autohide": 0, 
          "dismissible": false, 
          "prepend": true, 
          "classes": [], 
          "id": false
});

emit event for create() destroy()

Allow others to respond to new Toasts by emitting a custom event on create() and destroy()