hyper-modals

v2.0.2

Published

10 months ago

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

Downloads

0High
0Medium
0Low

hyper hypermodal hypermodals hyper-modal hyper-modals modal modals notification notifications js javascript ui communication jaaahn

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.

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

| Parameter name | Type | Description | | -------------- | ------ | ----------------------------------------- | | text | String | The text you want to display | | actions | Array | Array of options (details below) OPTIONAL | | config | Object | Your config (details below) OPTIONAL |

Actions

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

| Property name | Type | Available Arguments | Description | | ------------- | -------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | text | String | | Displayed text on button | | handler | Function | resolve(), reject(), close() | Run any code if user clicks on this action. You may also use the resolve() function to resolve the promise given by the component. Using an argument function will close the dialogue. | | style | String | | See Button Styles for available options |

Config

| Property name | Type | Default value | Description | | -------------------- | -------------- | ------------- | ------------------------------------------------------------------------------------------------------------------- | | description | String | null | | | throw | Boolean | false | Controls whether to fire reject ("throws an error") or just a resolve(false) if the user clicks on close button | | duration | Number (in ms) | 15000 | Duration of how long the notification will stay visible to the user | | autoClose | Boolean | true | | | dismissDescription | String | X-Icon | | | dismissStyle | String | "blue" | | | destination | String | "top-right" | Choose screen corner. Available options are "top-left", "top-right", "bottom-left" and "bottom-right". | | icon | Object | | Refer to docs: Icon Object | | theme | String | "match" | Refer to docs: Themes | | zIndex | String | 200 | Attention: can only be set globally via defaults |

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.

| Property name | Type | Available Argument | Description | | ------------- | -------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | text | String | | Displayed text on button | | handler | Function | resolve(), reject(), close() | Run any code if user clicks on this action. You may also use the resolve() function to resolve the promise given by the component. Using an argument function will close the dialogue. | | style | String | | See Button Styles for available options |

Config

| Property name | Type | Default value | Description | | -------------------- | ------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | description | String | null | | | throw | Boolean | false | Controls whether to fire reject ("throws an error") or just a resolve(false) if the user clicks on close button | | direction | String | "vertical" | If set to "horizontal", the actions are displayed in a flexbox container | | dismissDescription | String | "Dismiss" | | | dismissStyle | String | "secondary" | | | doBSL | Boolean | true | Whether body scrolling should be disabled or not. If doBSL = true, then the user will only be able to scroll within the modal, not the entire body. | | icon | Object | | Refer to docs: Icon Object | | theme | String | "match" | Refer to docs: Themes | | zIndex | String | 300 | Attention: can only be set globally via defaults |

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

| Parameter name | Type | Description | | -------------- | ------ | ------------------------------------------------------------------------- | | text | String | The text you want to display | | labels | Object | Choose custom labels for confirm and dismiss (details below) OPTIONAL | | config | Object | Your config (details below) OPTIONAL |

Labels

| Property name | Type | Default value | | ------------- | ------ | ------------- | | confirm | String | "Confirm" | | dismiss | String | "Dismiss" |

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

| Property name | Type | Default value | Description | | -------------------- | -------------- | ------------- | ------------------------------------------------------------------------------------------------------------------- | | description | String | null | | | throw | Boolean | false | Controls whether to fire reject ("throws an error") or just a resolve(false) if the user clicks on close button | | duration | Number (in ms) | 15000 | Duration of how long the notification will stay visible to the user | | autoClose | Boolean | true | | | dismissDescription | String | X-Icon | | | dismissStyle | String | "blue" | | | icon | Object | | Refer to docs: Icon Object | | theme | String | "match" | Refer to docs: Themes | | zIndex | String | 200 | Attention: can only be set globally via defaults |

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.

| Property name | Type | Default value | Description | | ------------- | ------ | ------------- | -------------------------------------------------------------------- | | html | String | null | HTML representation of your icon | | style | String | blue | Available Styles. Supports available button styles |

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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

HyperModals

This library does NOT include

Table of Contents

Installation via NPM as a module

Importing from CDN

Initialize Library (both Module and CDN)

Setting Defaults

Documentation

Notification

Example

Lifecycle

Function Blueprint

Parameters

Actions

Config

Available defaults for this component

Alert

Example

Lifecycle

Function Blueprint

Parameters

Actions

Config

Available defaults for this component

Confirm

Example

Lifecycle

Function Blueprint

Parameters

Labels

Config

Available defaults for this component

Snackbar

Example

Lifecycle

Function Blueprint

Parameters

Actions

Config

Available defaults for this component

Security advise

XSS Attacks

Tips and Tricks

Icon object

Themes

Button styles