npm install notification-js --save

Include both the script and css files within your html document:

<!-- During development -->
<script src="notification.js"></script>
<link rel="stylesheet" href="notification.css" />

<!-- For production -->
<script src="notification.min.js"></script>
<link rel="stylesheet" href="notification.min.css" />

Furthermore this library can be used as a AMD or Node module.

You can show a notification by calling:

// Simple way (with profile name and message)
notification.notify('success', 'Settings successfully saved.');

// Advanced way (plus additional options)
notification.notify('success', 'Settings successfully saved.', {
  // ...
});

You can clear all visible notifications by calling:

// Simple way
notification.clearAll();

// With no animation offset
notification.clearAll( false );

// With custom animation offset (in seconds, default is 0.15)
notification.clearAll( 0.3 );

// With a callback
notification.clearAll( function() { ... } );

// With both animation offset and callback
notification.clearAll( 0.3, function() { ... } );

You can clear just the newst notification by calling:

// Simple way
notification.clearNewest();

// With a callback
notification.clearNewest( function() { ... } );

You can clear just the oldest notification by calling:

// Simple way
notification.clearOldest();

// With a callback
notification.clearOldest( function() { ... } );

You may run into the situation that you fire multiple notifications and some of them are pretty similar when speaking about design and functionality. But you don't want to repeat yourself by passing in an options object again and again. There has to be a better way.

And there is! You have the ability to group similar notifications together by using the concept of profiles.

There are three different types of profiles:

• The global profile which contains all possible options with their default values, and therefore serves as the base configuration
• Predefined profiles like success, warning, error, default and info which contain some basic options (mostly colors) for their use cases
• And yes, your own profiles, for example message, confirmation or social

Options are combined / prioritized by the following hierarchy:

• Most important (and specific) are the options you pass in within the notify method
• Then all predefined profiles (e.g. success) or your own profiles are taken into account
• Lastly the global profile provides the values that are yet not set

You can add a brand new profile by calling:

// Create a new profile named 'social' without options
notification.addProfile('social');

// Create a new profile named 'social' with options
notification.addProfile('social', {
  // ...
});

You can overwrite profile options with your own options object by calling:

// Configure the 'social' profile
notification.configProfile('social', {
  // ...
});

You can remove any profile which is not predefined (e.g. global or success) by calling:

// Remove the 'social' profile
notification.removeProfile('social');

You can reset any profile which is not predefined (e.g. global or success) by calling:

// Reset the 'social' profile to global default options
notification.resetProfile('social');

You can get the options from a profile by calling:

// Get 'global' profile options
notification.getProfile('global');

You can check if a profile exists by calling:

// This returns true because the 'global' profile deos exist
notification.checkProfile('global');

The following presents an overview over all available options including detailed explanations and examples:

1. Notification options
2. Symbol options
3. Message options
4. Dismiss button options
5. Behaviour options
6. Animation options
7. Callbacks

This option defines the position on the screen in which notifications will appear. The first value is responsible for the x-axis (left | middle | right), the second value for the y-axis (bottom | top).

// Notifications will appear on the left bottom of the screen
position: ['left', 'bottom'];

This option defines distances: The first two values are responsible for the distance between the notification and each screen edge (x-axis, y-axis), the third value sets the vertical gap between multiple notifications.

// 20px distance to each screen edge (horizontal and vertical)
// 10px gap between notifications
distances: [20, 20, 10];

This option defines the notification height.

Note: Make sure to change this value carefully in order to prevent design issues.

// The notification has a height of 60px
height: 60;

This option defines the maximum notification width.

Note: The notification will not be wider than the screen size allows.

// The notification cannot be wider than the screen width
maxWidth: false;

// The notification cannot be wider that 500px
maxWidth: 500;

This option defines the corner roundness of the notification. Each value represents a corner, starting from the top left one and continuing clockwise.

Tip: Set all values half the notification height in order to make the notification round.

// No round corners
roundCorners: false;

// Each notification corner is 1px round
roundCorners: [1, 1, 1, 1];

This option defines the notification background color. Note that when changing this, you may also update other colors in order to maintain good readability (by preserving enough contrast).

Tip: HEX and RGB color values are recommended.

// Dark grey as the notification background color
color: '#666';

With this option you can enable or disable the notification symbol.

// Notification with a symbol
visibility: true;

// Notification without a symbol
visibility: false;

This option defines what the symbol should look like. Here you can either set an icon (e.g. checkmark for success feedback) or an image (e.g. user image for social use cases).

• When set to false the default symbol is being used (only for success, error profiles)
• You can set a string containing any valid svg code (to use inline svg)
• You can set a relative / absolute path pointing to an image of any format (e.g. jpg, png)
• You can set a function which returns a valid svg DOM element (to use inline svg)

Note: For quality and perf reasons the resource should be quadratic and optimally sized.

// Using the default symbol
resource: false

// String containing svg code
resource: '<svg> ... </svg>'

// Relative url to a PNG image
resource: 'img/symbols/email.png'

// Function that returns a beautifully designed svg icon
resource: function() {
	var svg = document.createElementNS( 'http://www.w3.org/2000/svg', 'svg' );
	// ...
	return svg;
}

This option defines the corner roundness of the symbol. Each value represents a corner, starting from the top left one and continuing clockwise.

Tip: Set all values half the notification height in order to make the symbol round.

// No round corners
roundCorners: false;

// Each symbol corner is 1px round
roundCorners: [1, 1, 1, 1];

This option defines the symbol highlight color. Note that this color might not visible when the symbol resource is an image with no transparency.

Tip: HEX, RGB or RGBA color values are recommended.

// No highlight color
color: false;

// Darker background highlight
color: 'rgba(0,0,0,.1)';

// Brighter background highlight
color: 'rgba(255,255,255,.15)';

With this option you can enable or disable the notification message.

Note: Hiding the notification message is not recommended.

// Notification with a message
visibility: true;

// Notification without a message
visibility: false;

This option defines the text color of the message.

Tip: HEX or RGB color values are recommended.

// White text color
color: '#FFF';

This option defines the text size of the message.

Tip: Make sure to change this value onyl slightly to prevent design issues.

// Font size of 14px
textSize: 14;

With this option you can enable or disable the notification dismiss button.

Tip: When disabling the dismiss button, make sure to at least enable auto hide.

// Notification with a dismiss button
visibility: true;

// Notification without a dismiss button
visibility: false;

This option defines the dismiss text color.

Tip: HEX or RGB color values are recommended.

// White text color
color: '#FFF';

This option defines whether a close icon or some custom text is being displayed within the dismiss button.

// Dismiss button with a close icon
text: false;

// Dismiss button named 'dismiss'
text: 'dismiss';

// Dismiss button named 'close'
text: 'close';

With this option you can define a time duration after which the notification will close itself automatically.

Tip: When disabling auto hide, make sure to at least provide a dismiss button.

// Notification stays open (like forever ...)
autoHide: false;

// Notification will close itself after 5 seconds
autoHide: 5;

This option defines what will happen when the user hovers over the notification area.

Note: This option only works if auto hide is enabled.

// Nothing will happen
onMouseover: false;

// The auto hide countdown will be paused
onMouseover: 'pause';

// The auto hide countdown will be reset (to its start value)
onMouseover: 'reset';

This option defines what will happen when more than one notification appear at the same time.

// Multiple notifications will be stacked up
stacking: true;

// Only one notification can exist at a time
stacking: false;

This option defines the maximum number (the limit) of notifications that can be open at the same time.

Note: This option only works if stacking is enabled.

// Show as many notifications as there is room for on the screen
limit: true;

// There must not be more that 4 notifications at a time
limit: 4;

// Show as many notifications as there is room for on the screen,
// but leave (unused) room for 2 more notifications
limit: -2;

// No limit of notifications
limit: false;

This option defines how the notification message will be rendered. Note that disabling this option generally gives you a higher performance as well as better security (e.g. against XSS).

Tip: When enabled you can use html markup like links (<a>) or text styling (<strong>).

// Plain text message
htmlMode: false;

// Message with html markup taken into account
htmlMode: true;

With this option you can turn all animations on or off. This option affects the whole notification with all its components.

Tip: You may temporarily turn off animations during development to speed up workflow.

// All animations are enabled
enabled: true;

// All animations are disabled
enabled: false;

This option defines how long animations are going to take from start to end. The first value represents the duration of things animating in, the second one of things animating out.

// 0.75s duration to both animate in and out
duration: [0.75, 0.75];

This option defines what animation easing function is being used; again the first value for things animating in, the second one for things animating out.

// Both animations (in and out) use the 'ease' function
easing: ['ease', 'ease'];

Here you can define functions that are being invoked when certain events occure. When set to false nothing will happen.

// Triggers when notification starts animating in
onOpen: function() { ... }

// Triggers when notification is fully animated in
onOpened: function() { ... }

// Triggers when notification start animating out
onClose: function() { ... }

// Triggers when notification is fully animated out
onClosed: function() { ... }

// Triggers when the user hits the dismiss button
onDismiss: function() { ... }

// Triggers when the user enters the notification area with the mouse
onMouseenter: function() { ... }

// Triggers when the user leaves the notification area with the mouse
onMouseleave: function() { ... }

The following shows all the default options (in the global profile) for every notification.

{
	notification: {
		position: [ 'left', 'bottom' ],
		distances: [ 20, 20, 10 ],
		height: 60,
		maxWidth: false,
		roundCorners: [ 1, 1, 1, 1],
		color: 'green'
	},
	symbol: {
		visible: true
		resource: false,
		roundCorners: false,
		color: 'rgba(0,0,0,.1)'
	},
	message: {
		visible: true,
		textSize: 14,
		color: '#FFF'
	},
	dismiss: {
		visible: true,
		color: '#FFF',
		text: false
	},
	behaviour: {
		autoHide: 5,
		onMouseover: 'pause',
		stacking: true,
		limit: true,
		htmlMode: false
	},
	animations: {
		enabled: true,
		duration: [ 0.75, 0.75 ],
		easing: [ 'ease', 'ease' ]
	},
	callbacks: {
		onOpen: false,
		onOpened: false,
		onClose: false,
		onClosed: false,
		onDismiss: false,
		onMouseenter: false,
		onMouseleave: false
	}
}

Instead of defining custom callback functions in the options object you can also react to notification events globally.

You can add a global notification event listener by calling:

// Short version
notification.on( 'open', function() { ... } );

// Vanilla JavaScript
document.addEventListener( 'notification.open', function() { ... } );

// jQuery
$('document').on( 'notification.open', function() { ... } )

You can remove a global notification event listener by calling:

// Short version
notification.off( 'open', function );

// Vanilla JavaScript
document.removeEventListener( 'notification.open', function );

// jQuery
$('document').off( 'notification.open', function )

The following list contains all available events. Next to the short event name (for the library specific methods) and the long event name (for the vanilla JavaScript or jQuery methods) there is also a description explaining when these events will be triggered.

This library should completely work with the following browser:

• Internet Explorer 10
• Microsoft Edge
• Mozilla Firefox 23
• Google Chrome 30
• Opera 17
• Safari 7.1