Growl-js
A classy notification system for the browser.
growl({ message: 'Excellent, Growl is working!', target: 'button' });
Features
- Easy to use.
- Lazy loading (3kb initial page load).
- Usable as a webpack/ES6 module or a pre-built browser bundle.
- Auto-positioning based on the target element's position.
- Target element can be specified by standard css selector, DOM element, or jQuery object.
- Automatic duration based on message length & type.
- Implements the 'Promise' interface, allowing sequential notifications.
Demo
Try meInstallation
Growl-js is a javascript package built for and using the ES6 module system, but it's also provided as a pre-built, minified browser package (in this package's "dist" folder).Browser
- Download & copy this package's "dist" folder into your web server's public folder eg.
public/js/dist/*. - Rename "dist" to "growl" eg.
public/js/growl - Load the growl script at the end of your web page (before the closing
bodytag) like this:
<body>
...
<script src="/js/growl/growl.js"></script>
</body>
</html>
- When the browser loads growl will be attached to the browser's global window object. Use it anywhere in your scripts like this:
<button>Target</button>
<script>
document.querySelector('button').onclick = function(event) {
growl({ message: 'You clicked on me' target: event.target });
});
</script>
ES6 module
Install the growl-js package into your project using npm:$ cd to/your/project $ npm install growl-js
Then import and use it in your project's ES6 modules:
Static import
import growl from 'growl';function helloWorld() { growl({ message: 'Hello World' }); }
Dynamic import
Leveraging Webpack's on-demand (lazy) loading and code-splitting:import(/* webpackChunkName: "growl" */ 'growl').then((module) => {
const growl = module.default;
growl({ message: 'Hey, growl just loaded dynamically', type: 'success' });
});
Growl Options
The growl function expects to be invoked with an options object. Eg.growl({ message: 'Hi' });
Here's the full list of options:
| Option | Type | Description | Default |
|---|---|---|---|
| message | (required) string | the message content to display (plain text or simple HTML) | [error] "Missing message content!" |
| type | (optional) string | the type of message ie. 'success', 'error', 'warning', or 'info'. | info |
| target | (optional) DOM element, CSS selector string, or jQuery object | (optional) element to associate the growl notification with. | #growlNoticeboard |
| duration | (optional) number | how long the message is displayed (in seconds). 0 => must be dismissed by the end-user. | automatic (based on message length/type) |
| overwrite | (optional) boolean | whether this growl message will replace any existing notification on the same target. | false |
Eg. using all the options:
growl({
message: 'You've selected "<strong>Delete my account</strong>"!',
type: 'warning',
target: 'input[type=submit]',
duration: 10,
overwrite: true
});
Sequential Notifications
Since growl.js implements the 'Promise' interface, your scripts can build sequential interactions with users. Eg: let clickCount = 0;
document.getElementById('target').onclick = function(event) {
growl({
message: `You've clicked this button ${++clickCount} times`,
type: 'info',
target: event.target,
overwrite: true
}).then(function() {
if (clickCount === 3) {
growl({
message: 'I hope you're enjoying our app!',
type: 'success',
});
}
});
};
Package Management
Growl-js supports npm under the name growl-js.
NPM
$ npm install growl-js --save
Dependencies
Growl-js depends on 2 external packages:- jquery
- animejs
- @aamasri/dom-utils
Invoking the growl() function will dynamically load these dependencies at run-time (if these scripts don't already exist on the page) and they'll be added to the global window object.
If your page already uses the jQuery, animejs, or @aamasri/dom-utils packages, growl will use them instead.
Manual release steps
- Increment the "version" attribute of `package.json`.
- Re-build the browser output bundle...
npm run build-production
...and observe that webpack completed with no errors. - Test the bundle by loading page: "dist/index.html" in a browser.
- Commit
git commit -a -m "Release version x.x.x - description"
- Tag the commit with it's version number
git tag x.x.x
- Change the "latest" tag pointer to the latest commit & push:
git tag -f latest git push origin master :refs/tags/latest git push origin master --tags
- Publish to npm registry:
npm publish
Authors
- Ananda Masri
- And awesome contributors