notific8

Notific8 is an on-page notification JavaScript library. Notific8 has built in themes which come with a set of built in colors for each. The library is designed to be easy to create new themes and colors. The library was born from a want for a simply designed yet modern and stylish notification system that was easily customizable and easy to use.

Version 5 included a major rewrite of the library to bring it up to modern standards and make it easier to use with other frameworks and libraries. Other major changes to the library include:

• Updated the code to Typescript including a typing for for using the library in Typescript-based projects
• Updated the testing library to use Jest
• Simplified the build setup

Install with NPM

$ npm install notific8 --save

Demo page

An interactive demo page can be found in the demo directory. The demo is written using the Vue library and the source code serves as an example of how to use Notific8 with other libraries and frameworks.

Features

• Promise-based functionality for more control
• Ability to reuse notification objects
• Notifications slide in and out from the designated corner of the page (default is upper right)
• Configurable life span of the notification
• Option to display a heading
• Built in theme options with ability to create custom themes (see CSS for built in themes)
• Ability to make the notification sticky
• Ability to set up custom settings for reuse without having to type them over and over
• Ability to set which corner the notifications are shown in
• Ability to set the z-index
• Ability to queue notifications
• Ability to add action buttons to notifications

Browser support

Currently supported and tested:

• Chrome
• Firefox
• Safari (Mac only)
• Edge (Windows desktop only)

While not tested, this library should work on Opera versions released after the swap to Chromium. From version 5 onward, the library no longer supports Internet Explorer and that will not be added.

As a rule of thumb, only the most recent plus one version older of a browser are supported unless marked otherwise.

Future development

All planned features can be viewed by visiting the issues page.

Styles

The styles are written in Scss format and available in the src/sass directory. Development will continue in Scss only - please do not open issues or pull requests to change the default style format. Contributions containing styles must be in Scss format.

Want to help?

Want to file a bug report or contribute some code? That's most awesome! Please view the guidelines for contributing before opening an issue or pull request.

Usage

import { Notific8 } from 'notific8';

Notific8.create('Test notification').then((notification) => {
    // open the notification
    notification.open().then(() => {
        console.log('Notification has been opened!');
    });
});

// async example
(async() => {
    const notification = await Notific8.create('Test notification');
    await notification.open();
    console.log('Notification has been opened!');
})();

Options

None of the options are required. Default values are available in the library and automatically set if not provided.

actionButtons: Notific8ActionButton[]

Provides action buttons to the notification. If an action is not provided, the button's action is set to close the notification. The option is an array of Notific8ActionButton interface.

Definition of Notific8ActionButton:

interface Notific8ActionButton {
  buttonAction: Function;
  buttonText: string;
}

closeHelpText: string

Help text shown when hovering over the close button.

closeReject: Function

The close function returns a promise. This option is used for the rejection of the promise when the notification is closed by the timer or clicking the close button.

closeResolve: Function

The close function returns a promise. This option is used for the resolution of the promise when the notification is closed by the timer or clicking the close button.

horizontalEdge: 'top'|'bottom'

Horizontal edge of the screen to display the notification against. Valid options are the strings 'top' and 'bottom'.

id: string

Queriable ID given to the notification.

imageAltText: string

Alternate text on the image provided with the imageUrl option. If this is provided but imageUrl is not, this option will be ignored.

imageUrl: string

URL of the image to display on the notification.

life: number

Life of the notification until it automatically closes. If the sticky option is applied, this value is ignored.

queue: boolean

Whether or not to add the notification to the queue. The first notification sent in with the queue option true will be automatically opened if there are no notifications on the screen.

queueOpenReject: Function

The open function returns a promise. This option is used for the rejection of the promise when the notification is opened by the queue.

queueOpenResolve: Function

The open function returns a promise. This option is used for the resolution of the promise when the notification is opened by the queue.

sticky: boolean

Whether or not the notification should stay open until the user closes it. If the life option is passed in with this option, the life option will be ignored.

title: string

Heading to apply to the notification.

theme: string

Theme to add to the notification for styling. See the themes page for more information.

themeColor: string

Color of the theme to style the notification. See the themes page for more information.

verticalEdge: 'left'|'right'

Vertical edge of the screen to display the notification against. Valid options are the strings 'left' and 'right'.

zIndex: number

Z-index for layer to display the notification.

Notification API

open(): Promise

Opens the notification object. Returns a promise.

close(): Promise

Closes the notification object. Returns a promise.

Notific8 API

getDefaultOptions(): NotificationOptions

Get the default options set for the library.

setDefaultOptions(newDefaultOptions: Notific8Options): void

Set any number of default options at one time by passing in an object that complies with the Notific8Options interface.

setDefaultOption(option: string, newValue: string|number|boolean|Notific8ActionButton[]): void

Set a specific default option. The passed in option's value must comply with the property in the Notific8Options interface.

isNotific8OptionsObjectValid(optionsToCheck: object): boolean

Returns whether or not the passed in notifcation options object is valid.

create(message: string, notificationOptions: Notific8Options = notific8DefaultOptions): Promise

Creates a new notification with the passed in notification message and optional notification options object.

queueOrAddToContainer(notification: Notific8Notification): void

Determines whether to queue or add the passed in notification to a container.

hasQueuedNotifications(): boolean

Returns whether or not there are notifications in the queue.

triggerQueue(): void

Triggers the queue to fire.

License

The notific8 library is released under the MIT license.

(c) 2013-2019 Pynk Lynn LLC