Simple Notifier
A lightweight and easy to use notification library, written in modern ECMAScript.
Table of Contents
Nice features
- An instance allows either at most a single notification to be shown on screen, or multiple simultaneously.
- Flexible positioning.
- Small and lightweight.
- Check out the options for more!
Basic usage
const notifier = new SimpleNotifier();
notifier.init();
// Wrapper element is inserted at the top of <body>.
// <div class="simple-notifier simple-notifier--pos-y-top simple-notifier--pos-x-center">
// </div>
const message = "This is an example message.";
const type = "success";
notifier.show(message, type);
// Notification is shown for 3500 ms.Browser support
The distributables are compiled with the following browserslist:
"since 2019-01 and > 0.5%",
"last 2 versions and not dead",
"Firefox ESR",
"not Explorer >= 0",
"not OperaMini all"
Installation
Usage with a module bundler
// Install package from npm
npm install @codebundlesbyvik/simple-notifier`// Import the module
import SimpleNotifier from "@codebundlesbyvik/simple-notifier";// Import the stylesheet
@import "@codebundlesbyvik/simple-notifier";
// Will import the Sass file if your project utilizes Sass, should automatically import the compiled CSS file otherwise.Usage as a standalone package
Via CDN (jsdelivr)
<!-- Import the UMD bundle -->
<script src="https://cdn.jsdelivr.net/npm/@codebundlesbyvik/simple-notifier@1.1.2/dist/js/simple-notifier.bundle.min.js" crossorigin="anonymous"></script><!-- Link to the stylesheet -->
<link href="https://cdn.jsdelivr.net/npm/@codebundlesbyvik/simple-notifier@1.1.2/dist/css/simple-notifier.min.css" rel="stylesheet" crossorigin="anonymous">Local
Download the latest release from the GitHub releases page.
<!-- Import the UMD bundle -->
<script src="./dist/js/simple-notifier.bundle.min.js"></script>// Link to the stylesheet in HTML ...
<link href="./dist/simple-notifier.min.css" rel="stylesheet">
// ... or import it in your main CSS file.
@import "./dist/simple-notifier.min.css";
Options
JavaScript
Options should be passed in as an object on instance creation.
| Parameter | Type | Default | Description |
|---|---|---|---|
autoHide |
Number / Boolean
|
3500 |
Time in milliseconds after which .hide() will be automatically called. true defaults to 3500, set to false or 0 to make the notification(s) sticky. |
onlyOneNotification |
Boolean |
true |
Whether the instance is allowed to show multiple notifications on screen simultaneously or not. |
parentEl |
Element |
document.body |
Instance's parent element. |
position |
String |
top center |
On-page position of the wrapper element. Accepted value is a combination of top or bottom and left, center or right. |
animations |
String / Boolean
|
"auto" |
Animation preference. "auto" checks user's device motion preference on each action. |
Sass
Colors can be customized using Sass variables.
| Variable name | Type | Description |
|---|---|---|
$notifier-types |
Map |
Notification types. |
$notifier-font-size |
Dimension |
Base font-size. Internal sizing is done relative to this value. Default is 1rem. |
$notifier-color-opacity |
Number |
Opacity applied to the defined colors. Default is 0.9. |
$notifier-colors |
Map |
Available colors. |
$notifier-text-colors |
Map |
Text color to use with given notification type. |
$notifier-bg-colors |
Map |
Background color to use with given notification type. |
Methods
.init()
Initialize a SimpleNotifier instance.
.destroy()
Destroy a SimpleNotifier instance.
.show(text, type)
Show a notification.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
text |
String |
Some dummy text. | Text to show. |
type |
String |
"dummy" if text is undefined, else "default"
|
Element's parent. Will be added as class (BEM modifier) to the wrapper element. |
.hide(notificationId)
Hide a currently shown notification.
If onlyOneNotification is set to true, passing in a notificationId is not required.
If onlyOneNotification is set to false, passing in a notificationId will hide that specific notification. Not passing in any notificationId will hide all currently shown notifications.
Events
| Event | Fired when ... |
|---|---|
notificationShown |
The process of showing a notification has fully completed. |
notificationDestroyed |
The process of destroying a notification has fully completed. |
allNotificationsDestroyed |
The last visible notification has been destroyed. |
License
Mozilla Public License 2.0 © Viktor Chin-Kon-Sung