xz-notify

v3.0.5

Published

4 months ago

Notifications based on web components.

Downloads

204

0High
0Medium
0Low

dknight

notification notice alert web components agnostic vanilla

XZ Notify

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

Check out the demo page for more examples.

Install

NPM Package

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