XZ Notify

XZNotify is a framework-agnostic web component to shows floating notifications on the web page.

Check out the demo page for more examples.

Install

npm install --save xz-notify

Or just download the source and include it in your HTML.

Usage

You can create as many notifications as you want. These will be automatically positioned and removed from the DOM after they expire or are closed.

XZNotify is a module. First of all, you need to include it in your project. At the moment, there are two ways to do it:

script tag way

<script type="module" src="./xz-notify.js"></script>

CDN

Just include link from CDN and you are ready to go.

<!-- preferably in <head> -->
<script
  src="https://unpkg.com/xz-notify@latest/dist/xz-notify.min.js"
  type="module"
></script>
<!-- inside <body> -->
<xz-notify expire="150000">Hello world!</xz-notify>

import way

import XZNotify from 'xz-notify';

After being added, there will be a custom HTML element <xz-notify> defined in your document.

Basic usage

The notification can be inserted directly into your HTML, and it will be destroyed as soon as it expires.

<xz-notify type="info" expire="10000" position="ne"> Hello world! </xz-notify>

Another way is to make it programmatically and append it to any element, but <body> or something like <main> is recommended.

const notification = XZNotify.create('Hello world', {
  type: 'info',
  expire: 10000,
  position: 'ne',
});
document.body.appendChild(notification);

API

XZNotify

Class has some properties that are reflected in HTML attributes.

name	type	default	description.
expire	number	10000	Time in milliseconds. How long the notification will be displayed. If expire is zero or less, the notification will be closed immediately. If the expiration value cannot be parsed into a number, then the default fallback is used.
type	string	"default"	Type of the notification. There are built-in types: default, info, success, warning, and error.
position	string	"ne"	Position of the notification o the screen. Position corresponds to point of compass: n (north), ne (north-east), s (south), etc.
closeable	boolean	false	If it is set, clicking on the notification will close it.
grouped	boolean	false	If grouped is set, then the offset position is not recalculated and notifications are stacked.
heading	string	null	The heading of the notification.

create(content, attributes?, trusted?)

Method to create XZNotify instance.

name	type	default	description
content	string		Content of the notification.
attributes	Object	{}	Attributes of the `<xz-notify>` element.
trusted	boolean	false	If `true` then HTML is allowed in content. Might not be safe for XSS.

Events

Notification dispatches custom events on the open state and when expired.

event name	detail
xz-notify:open	XZNotify
xz-notify:close	XZNotify

document.body.addEventListener('xz-notify:open', (e) => console.log(e));
document.body.addEventListener('xz-notify:close', (e) => console.log(e));

Collection

XZNotify class has static collection variable which contains currently opened and live notifications.

XZNotify.collection; // -> NodeList<XZNotify>
XZNotify.collection.length; // 0 - means that none of live notifications exist

Styling

Use the full power of CSS to style notifications. Just declare style wherever you want and overwrite defaults in the manner of:

xz-notify {
  border: 2px solid #000;
  color: #000;
  background: none;
  /* etc... */
}

Custom properties

XZNotify exposes some useful CSS custom properties. Most likely, you won't change them manually.

--xz-notify-heading-color
--xz-notify-zIndex
--xz-notify-background-color

Themes

Include the theme in the HTML file:

<link rel="stylesheet" href="bootstrap.css" />

At the moment, there are some built-in themes. More themes will be added in future.

default
bootstrap
simple
bar

Contribution

Any help is appreciated. Found a bug, typo, inaccuracy, etc.? Please do not hesitate to make a pull request or file an issue.

License

MIT 2023

dknight/xz-notify