hyper-modals v2.0.0

HyperModals

HyperModals is a framework agnostic library to create alerts, notifications and other interactive UI popups.

This library does NOT include

• Modals (yes, i know, the name of this library is misleading)
• Popovers and Tooltips

One of my other projects is HyperUI, a Vue Component Library that does ship these components.

Table of Contents

• Installation via NPM as a module
• Importing from CDN
• Initialize Library (both Module and CDN)
• Setting Defaults
• Documentation
  • Notification
  • Alert
  • Confirm
  • Snackbar
• Security advise
  • XSS Attacks
• Tips and Tricks
  • Icon object
  • Themes
  • Button styles

Installation via NPM as a module

Run the command: npm i hyper-modals

And import the library in your entry JS file (index.js, main.js, etc.):

import hm from "hyper-modals";
import "hyper-modals/styles";

Importing from CDN

<script src="https://cdn.jsdelivr.net/npm/hyper-modals@next/dist/hyper-modals.umd.js"></script>

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/hyper-modals@next/dist/index.css" />

Or go to jsDelivr to view more options.

Initialize Library (both Module and CDN)

hm.initialize();

Setting Defaults

let defaults = {
    notifications: {
        // any notification related defaults
    },

    alerts: {
        // any alert related defaults
    },

    snackbars: {
        // any snacbar related defaults
    },
};

hm.initialize(defaults);

Passing defaults is optional. You may omit any key that you want to leave unchanged.
Available default options are listed in the component documentation.
Defaults can be overriden via the config object when instantiating a component.

Documentation

Notification

Example

// EASY EXAMPLE
hm.notification("Hello World");

// ADVANCED USAGE
let result = await hm.notification(
    "Hello, how are you?",
    [
        {
            text: "I'm fine",
            handler(resolve, reject, close) {
                resolve("fine");
            },
        },
    ],
    {
        description: "Description Text",
        duration: 10 * 1000,
        throw: true,
        icon: {
            html: "<i class='icon-sparkles'></i>" // Use your own icons; Tested with an icon font
            style: "yellow"
        },
        theme: "contrast"
    }
);

Lifecycle

• Returns a promise fulfilled if user clicks on action or dismiss button
• Throws if user clicks on dismiss button and config.throw = true

Function Blueprint

hm.notification(text: String, actions: Array, config: Object) : Promise

Parameters

Actions

An action is a button that is being displayed next to the close button of the component.

Config

Available defaults for this component

throw, duration, autoClose, dismissDescription, dismissStyle, destination, icon, theme, zIndex

Alert

Example

// EASY EXAMPLE
hm.alert("Hello, nice to meet you!");

// ADVANCED USAGE
let result = await hm.alert(
    "Hello, how are you?",
    [
        {
            text: "I'm fine",
            handler(resolve, reject, close) {
                resolve("fine");
            },
        },
    ],
    {
        description: "Description Text",
        direction: "vertical",
        dismissDescription: "Close alert",
        throw: true,
        icon: {
            html: "<i class='icon-sparkles'></i>" // Use your own icons; Tested with an icon font
            style: "yellow"
        },
        theme: "white"
    }
);

Lifecycle

• Returns a promise fulfilled if user clicks on action or dismiss button
• Throws if user clicks on dismiss button and config.throw = true

Function Blueprint

hm.alert(text: String, actions: Array, config: Object) : Promise

Parameters

Actions

An action is a button that is being displayed next to the close button of the component.

Config

Available defaults for this component

throw, direction, dismissDescription, dismissStyle, doBSL, icon, theme, zIndex

Confirm

Example

let result = await hm.confirm("Do you want to delete this?");

Lifecycle

• Returns a promise fulfilled with true or false if user clicks on action or dismiss button

Function Blueprint

hm.confirm(text: String, labels: Object, config: Object) : Promise

Parameters

Labels

Config

A confirm supports all config options of Alerts, EXCEPT for dismissDescription and throw.

Available defaults for this component

This component will use the defaults of Alerts.

Snackbar

Example

// EASY EXAMPLE
hm.snackbar("Hello World");

// ADVANCED USAGE
let result = await hm.snackbar(
    "Hello, how are you?",
    [
        {
            text: "I'm fine",
            handler(resolve, reject, close) {
                resolve("fine");
            },
        },
    ],
    {
        description: "Description Text",
        duration: 10 * 1000,
        throw: true,
        icon: {
            html: "<i class='icon-sparkles'></i>" // Use your own icons; Tested with an icon font
            style: "yellow"
        },
        theme: "black"
    }
);

Lifecycle

• Returns a promise fulfilled if user clicks on action or dismiss button
• Throws if user clicks on dismiss button and config.throw = true

Function Blueprint

hm.snackbar(text: String, actions: Array, config: Object) : Promise

Parameters

Actions

An action is a button that is being displayed next to the close button of the component.

Config

Available defaults for this component

throw, duration, autoClose, dismissDescription, dismissStyle, icon, theme, zIndex

Security advise

XSS Attacks

All components that support a text, description and dismissDescription attribute, use .innerHTML to display these values. This enables not only a high degree of customization but also allows attackers to run malicious code.
Please make shure to always check your content.

Tips and Tricks

Icon object

Some components support displaying an icon. We tested it with icon fonts, but SVG icons should work too.

Themes

Available themes are white, black, match, contrast.

The match / contrast themes will choose the white or black theme respectively depending on the user's preferred color scheme.

Button styles

Available options are secondary, blue, pink, yellow, green, red, purple.