toast-me

    1.3.5 • Public • Published

    toast-me

    npm version Build Status

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

    Demo

    Table of Contents

    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');
    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!'),
      },
    );

    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):

    {
      position: 'top',
      type: 'over',
      toastClass: '',
      removedToastClass: '',
      containerClass: '',
      useUniqueContainer: 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
    • 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

    Install

    npm i toast-me

    DownloadsWeekly Downloads

    98

    Version

    1.3.5

    License

    MIT

    Unpacked Size

    43.3 kB

    Total Files

    17

    Last publish

    Collaborators

    • avatar