Flexible and themeable notification plug-in for JavaScript. The plug-in contains multiple themes, each offering a built in selection of colors and Sass mixins to easily create custom colors to match your site's color scheme.
MIT License
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:
$ npm install notific8 --save
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.
Currently supported and tested:
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.
All planned features can be viewed by visiting the issues page.
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 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.
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!');
})();
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
: stringHelp text shown when hovering over the close button.
closeReject
: FunctionThe 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
: FunctionThe 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
: stringQueriable ID given to the notification.
imageAltText
: stringAlternate text on the image provided with the imageUrl
option. If this is provided but imageUrl
is not, this option will be ignored.
imageUrl
: stringURL of the image to display on the notification.
life
: numberLife of the notification until it automatically closes. If the sticky
option is applied, this value is ignored.
queue
: booleanWhether 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
: FunctionThe open function returns a promise. This option is used for the rejection of the promise when the notification is opened by the queue.
queueOpenResolve
: FunctionThe open function returns a promise. This option is used for the resolution of the promise when the notification is opened by the queue.
sticky
: booleanWhether 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
: stringHeading to apply to the notification.
theme
: stringTheme to add to the notification for styling. See the themes page for more information.
themeColor
: stringColor 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
: numberZ-index for layer to display the notification.
open()
: PromiseOpens the notification object. Returns a promise.
close()
: PromiseCloses the notification object. Returns a promise.
getDefaultOptions()
: NotificationOptionsGet the default options set for the library.
setDefaultOptions(newDefaultOptions: Notific8Options)
: voidSet 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[])
: voidSet a specific default option. The passed in option's value must comply with the property in the Notific8Options interface.
isNotific8OptionsObjectValid(optionsToCheck: object)
: booleanReturns 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)
: voidDetermines whether to queue or add the passed in notification to a container.
hasQueuedNotifications()
: booleanReturns whether or not there are notifications in the queue.
triggerQueue()
: voidTriggers the queue to fire.
The notific8 library is released under the MIT license.
(c) 2013-2019 Pynk Lynn LLC