Narwhals Prolong Mischief

    notyf
    TypeScript icon, indicating that this package has built-in type declarations

    3.10.0 • Public • Published

    Notyf

    npm version Cypress.io tests npm downloads size jsdelivr

    Notyf is a minimalistic JavaScript library for toast notifications. It's responsive, A11Y compatible, dependency-free and tiny (~3KB). Easy integration with React, Angular, Aurelia, Vue, and Svelte.

    demo gif

    Features

    • 📱 Responsive
    • 👓 A11Y compatible
    • 🔥 Strongly typed codebase (TypeScript Typings readily available)
    • ⚡️ 4 types of bundles exposed: ES6, CommonJS, UMD, and IIFE (for vanilla, framework-free usage).
    • 🎯 End-to-end testing with Cypress
    • 🎸 Easily plugable to modern frameworks. Recipes available to integrate with React, Angular, Aurelia, Vue, and Svelte.
    • Optional ripple-like fancy revealing effect
    • 😈 Simple but highly extensible API. Create your own toast types and customize them.
    • 🎃 Support to render custom HTML content within the toasts
    • 🐣 Tiny footprint (<3K gzipped)
    • 👴🏽 Works on IE11

    Demo: carlosroso.com/notyf

    Installation

    npm i notyf
    

    Usage

    This section explains the base case using the minified bundle. See the quick recipes section for instructions to plug Notyf into Angular, React, Aurelia, Vue, or Svelte.

    Add the css and js files to your main document:

    <html>
      <head>
        ...
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/notyf@3/notyf.min.css">
      </head>
      <body>
        ...
        <script src="https://cdn.jsdelivr.net/npm/notyf@3/notyf.min.js"></script>
      </body>
    </html>

    Files are delivered via CDN by jsdeliver

    Basic

    // Create an instance of Notyf
    var notyf = new Notyf();
    
    // Display an error notification
    notyf.error('You must fill out the form before moving forward');
    
    // Display a success notification
    notyf.success('Your changes have been successfully saved!');

    With module bundlers

    Notyf ships with an ES6 bundle referenced from the module key of its package.json. This is the file that module bundlers like Webpack will use when using the package. Notyf is exported as a class under the notyf namespace. Typings are also available.

    import { Notyf } from 'notyf';
    import 'notyf/notyf.min.css'; // for React, Vue and Svelte
    
    // Create an instance of Notyf
    const notyf = new Notyf();
    
    // Display an error notification 
    notyf.error('Please fill out the form');

    API

    You can set some options when creating a Notyf instance.

    new Notyf(options: INotyfOptions)

    Param Type Default Details
    duration number 2000 Number of miliseconds before hiding the notification. Use 0 for infinite duration.
    ripple boolean true Whether to show the notification with a ripple effect
    position INotyfPosition {x:'right',y:'bottom'} Viewport location where notifications are rendered
    dismissible boolean  false Whether to allow users to dismiss the notification with a button
    types INotyfNotificationOptions[] Success and error toasts Array with individual configurations for each type of toast

    dismiss(notification: NotyfNotification)

    Dismiss a specific notification.

    const notyf = new Notyf();
    const notification = notyf.success('Address updated');
    notyf.dismiss(notification);

    dismissAll()

    Dismiss all the active notifications.

    const notyf = new Notyf();
    notyf.success('Address updated');
    notyf.error('Please fill out the form');
    notyf.dismissAll();

    Events

    Every individual notification emits events. You can register listeners using the on method.

    'click'

    Triggers when the notification is clicked

    const notyf = new Notyf();
    const notification = notyf.success('Address updated. Click here to continue');
    notification.on('click', ({target, event}) => {
      // target: the notification being clicked
      // event: the mouseevent
      window.location.href = '/';
    });

    'dismiss'

    Triggers when the notification is manually (not programatically) dismissed.

    const notyf = new Notyf();
    notyf
      .error({
        message: 'There has been an error. Dismiss to retry.',
        dismissible: true
      })
      .on('dismiss', ({target, event}) => foobar.retry());

    Interfaces

    INotyfPosition

    Viewport location where notifications are rendered.

    Param Type Details
    x left | center | right x-position
    y top | center | bottom y-position

    INotyfNotificationOptions

    Configuration interface for each individual toast.

    Param Type Details
    type string Notification type for which this configuration will be applied
    className string Custom class name to be set in the toast wrapper element
    duration number 2000
    icon string INotyfIcon false Either a string with HTML markup, an object with the properties of the icon, or 'false' to hide the icon
    background string Background color of the toast
    message string Message to be rendered inside of the toast. Becomes the default message when used in the global config.
    ripple boolean Whether or not to render the ripple at revealing
    dismissible boolean Whether to allow users to dismiss the notification with a button

    INotyfIcon

    Icon configuration

    Param Type Details
    className string Custom class name to be set in the icon element
    tagName string HTML5 tag used to render the icon
    text string Inner text rendered within the icon (useful when using ligature icons)
    color string Icon color. It must be a valid CSS color value. Defaults to background color.

    Examples

    Global configuration

    The following example configures Notyf with the following settings:

    • 1s duration
    • Render notifications in the top-right corner
    • New custom notification called 'warning' with a ligature material icon
    • Error notification with custom duration, color and dismiss button
    const notyf = new Notyf({
      duration: 1000,
      position: {
        x: 'right',
        y: 'top',
      },
      types: [
        {
          type: 'warning',
          background: 'orange',
          icon: {
            className: 'material-icons',
            tagName: 'i',
            text: 'warning'
          }
        },
        {
          type: 'error',
          background: 'indianred',
          duration: 2000,
          dismissible: true
        }
      ]
    });

    Custom toast type

    Register a new toast type and use it by referencing its type name:

    const notyf = new Notyf({
      types: [
        {
          type: 'info',
          background: 'blue',
          icon: false
        }
      ]
    });
    
    notyf.open({
      type: 'info',
      message: 'Send us <b>an email</b> to get support'
    });

    Warning: Notyf doesn't sanitize the content when rendering your message. To avoid injection attacks, you should either sanitize your HTML messages or make sure you don't render user generated content on the notifications.

    Default types with custom configurations

    The default types are 'success' and 'error'. You can use them simply by passing a message as its argument, or you can pass a settings object in case you want to modify its behaviour.

    const notyf = new Notyf();
    
    notyf.error({
      message: 'Accept the terms before moving forward',
      duration: 9000,
      icon: false
    })

    Recipes

    Notyf is well supported in all of the modern frameworks such as Angular, React, Aurelia, Vue, or Svelte. Check out the recipes and learn how to integrate the library to your application.

    Contributing

    Please see the contributing document and read the contribution guidelines. Thanks in advance for all the help!

    Licence

    Notyf is under MIT licence

    Install

    npm i notyf

    DownloadsWeekly Downloads

    19,861

    Version

    3.10.0

    License

    MIT

    Unpacked Size

    88.1 kB

    Total Files

    13

    Last publish

    Collaborators

    • caroso1222