toast-me

toast-me

Tiny, easy to use tool to show toast-like notifications on the web page.

You can read the CHANGELOG.

Table of Contents

• Features
• How to use
  • Install
  • Import module to your script
  • Use
  • Use with own customization
  • Use with options preset
  • Use with own customization and action button
  • Use with action button but no customizations
  • Use with HTML
  • Use with React
• Toast function arguments
  • Message argument
  • Options argument
    • Accepted options
    • Options presets
  • Action argument
• Instance of ToastMeClass
• class ToastMeClass
• Contributing
  • Getting started
  • Scripts
  • Structure
  • Readings

Features

• Exported in a umd format so works everywhere
• Fully compatible with popular frameworks, such as React, Vue, Angular, jQuery, etc
• Customizable
• Light-weight (17kB until gzip, 6kB zipped)
• Supports actions' button inside toast
• Closeable
• Pauses toast's timer on hover
• Accepts CSS classes for styling

How to use

Install package from npm

yarn add toast-me
# or
npm install toast-me

Import module to your script

import toast from 'toast-me';

Use

toast('My message');
// or with the instance
const toastInstance = toast('My message');

Use with own customization

toast('My message', { duration: 3000, toastClass: 'my-toast-class' /* ... */ });

Use with options preset

toast('My message', 'error');

Use with own customization and action button

toast(
  'My message',
  { duration: 1000 },
  {
    label: 'Confirm',
    action: () => alert('Cool!'),
    class: 'my-custom-class', // optional, CSS class name for action button
  },
);

Use with action button but no customizations

toast(
  'My message',
  null,
  {
    label: 'Confirm',
    action: () => alert('Cool!'),
  },
);

Use with HTML

toast(
  '<i>My message</i> &#9787;',
  { useUnsafeHtmlContent: true },
);

Use with React

const uniqId = 'messageRoot_' + Math.random().toString().slice(2);

toast(`<div id="${uniqId}" />`, { useUnsafeHtmlContent: true });

ReactDOM.render(
  <div>My message</div>,
  document.getElementById(uniqId)
)

Toast function arguments

toast(message, [options, [action]]);

Function accepts three arguments:

• message - message to show in toast,
• options - toast customization options,
• action - some action button options.

Returns instance of ToastMeClass. You can learn method of it here

Message argument

Accepts string, any message to put in toast. Text shown in one line, no wraps allowed. Overflowed text will be hidden with ellipsis. Complete text shown on hover with the title attribute on toast node.

Options argument

Optional. Accepts object with any allowed fields, or string as a name of options preset, or null. If you don't need to set options, but need to pass an action - pass null instead options.

Accepted options

Default options preset (all available options with their default values):

const defaults = {
  position: 'top',
  type: 'over',
  toastClass: '',
  removedToastClass: '',
  containerClass: '',
  useUniqueContainer: false,
  useUnsafeHtmlContent: false,
  closeable: true,
  timeoutOnRemove: 1000,
  duration: 5000,
}

• position - string, one of "top" "bottom". Default "top".
• type - string, one of "over" "chain". When "chain" - all messages shown in line, and when "over" - message covers previous. Default "over". NOTE: when you use toasts of different types in one app - that could cause toast display collisions.
• toastClass - string, CSS class name for toast node, can be used for custom toast styling. Default "" - empty string
• removedToastClass - string, CSS class name for removed toast node, can be used for custom CSS animation or styling. Default "" - empty string
• containerClass - string, CSS class name for toast's container node, can be used for custom container styling. Once it is set, container node will have that class (classname won't be erased on next toast creating). If you want prevent this behaviour - set useUniqueContainer option to true when set containerClass. Default "" - empty string
• useUniqueContainer - boolean, create new toast's container node, instead of re-using existing one, if it is presented. Default false
• useUnsafeHtmlContent - boolean, allows passing HTML string as content. Default false
• closeable - boolean, enables/hides "close" button on toast. Default true
• timeoutOnRemove - number, time in ms, till node should be removed from DOM after toast hides. Can be useful when you change hide animation by CSS and set new animation duration. To avoid element disappearing until animation ends set this option to larger or equal value than animation duration. Default 1000
• duration - number, time in ms, how long should toast be shown. Default 5000

Options presets

• default - all default options,
• error - everything default, except background color - #D40D00, set by CSS class.

Action argument

Optional. Accepts object with three fields:

• label - string, text to put in button.
• action - callback function - to be called on button click.
• class - string, CSS class for button node.

Instance of ToastMeClass

Has methods:

• close() - Closes current toast.
• startTimer() - Starts/restarts timer with timeout, set in options object on toast create.
• stopTimer() - Stops timer, the toast won't disappear. After calling this you should handle toast's behavior by yourself (i.e. with close() method).

import toast from 'toast-me';

const message = toast('Something');
// ...
message.stopTimer();
// ...
message.close();

class ToastMeClass

Has static methods:

• removeAll(position) - Closes all toasts in that position. Accepts one argument position, default "top" (described in options section)

import { ToastMeClass } from 'toast-me';

ToastMeClass.removeAll('bottom');

This method has separate simplified alias

import { removeAllToasts } from 'toast-me';
removeAllToasts('bottom')

Contributing

Getting started

You will need node.js and preferred to have yarn to run the project.

Copy project to your local folder and then run in project's root folder next command to load dependencies:

yarn

Scripts

When you load all dependencies, you able to run several commands:

• yarn build - produces production pack of library under the lib folder
• yarn run-dev - produces development version of your library, runs file watcher and http server on http://localhost:3005
• yarn watch - produces development version of your library, runs a file watcher
• yarn test - runs the tests

Structure

• Root folder
  • dev/ - Folder, containing development environment files. This folder is server with webpack-dev-server with yarn run-dev command. toast-me.js and toast-me.js.map files inside are generated by webpack watcher from /src folder. You are able to change files in both folders and they are to be reloaded in browser.
  • lib/ - The place production pack will be located after build. Usually you won't need it, until you wan't to compile library by yourself and insert in your project manually
  • scripts/ - Node.js executable scripts' folder, such as dev-server.js or test.js.
    • config/ - Configuration files' folder.
  • src/ - Here is the code of library itself.

Readings

1. Git-flow workflow
2. AirBnB Style Guide
3. Webpack
4. Node.js
5. Yarn
6. SASS
7. Jest