Demo
You can play around with this library with this Plunker right here.
Table of Contents
Also, see the Changelog as well as at the MIT License. Or learn about me.
How to install
To get angular-notifier via npm, simply add it as a new dependency to your package.json
file and run npm install
. Alternatively, install it directly by running:
npm install angular-notifier --save
Browser Support & Polyfills
By default, meaning without any polyfills, angular-notifier should be compatible with the latest versions of Chrome, Firefox, and
Opera. Bringing in the following polyfills will extend the browser support:
- To be able to use the latest and greatest JavaScript features in older browsers (e.g. older version of IE & Safari), you might want to
add core-js to your polyfills.
- For animation support (in particular, for better
Web Animations API support), you might want to use the web-animations-js polyfill. For details, see the corresponding
CanIUse page.
For detailed information about the Angular browser support read the
official Angular browser support documentation. If you generated your
Angular project with the Angular CLI, all the polyfills mentioned above do already exist in
your polyfills.ts
file - waiting for you to enable and install them.
How to setup
Before actually being able to use the angular-notifier library within our code, we have to first set it up within Angular, and also
bring the styles into our project.
1. Import the NotifierModule
First of all, make angular-notifier globally available to your Angular application by importing (and optionally also configuring) the
NotifierModule
the your root Angular module. For example:
import { NotifierModule } from 'angular-notifier';
@NgModule( {
imports: [
NotifierModule
]
} )
export class AppModule {}
But wait -- your probably might want to customize your notifications' look and behaviour according to your requirements and needs. To do so,
call the withConfig
method on the NotifierModule
, and pass in the options. For example:
import { NotifierModule } from 'angular-notifier';
@NgModule( {
imports: [
NotifierModule.withConfig( {
} )
]
} )
export class AppModule {}
2. Add the notifier-container
component
In addition, you have to place the notifier-container
component somewhere in your application, best at the last element of your
root (app) component. For example:
@Component( {
selector: 'app',
template: `
<h1>Hello World</h1>
<x-notifier-container></x-notifier-container>
`
} )
export class AppComponent {}
Later on, this component will contain and manage all your applications' notifications.
3. Import the styles
Of course we also need to import the angular-notifier styles into our application. Depending on the architecture of your Angular
application, you want to either import the original SASS files, or the already compiled CSS files instead - or none of them if you wish to
write your own styles from scratch.
The easy way: Import all the styles
To import all the styles, simple include either the ~/angular.notifier/styles.(scss|css)
file. It contains the core styles as well as all
the themes and notification types.
The advanced way: Only import the styles actually needed
To keep the size if your styles as small as possible (improving performance for the perfect UX), your might instead decide to only import
the styles actually needed by our application. The angular-notifier styles are modular:
- The
~/angular-notifier/styles/core.(scss|css)
file is always required, it defines the basic styles (such as the layout) - Themes can be imported from the
~/angular-notifier/styles/theme
folder - The different notification types, then, can be imported from the
~/angular-notifier/styles/types
folder
How to use
Using angular-notifier is as simple as it can get -- simple import and inject the NotifierService
into every component (directive,
service, ...) you want to use in. For example:
import { NotifierService } from 'angular-notifier';
@Component( {
} )
export class MyAwesomeComponent {
private readonly notifier: NotifierService;
constructor( notifierService: NotifierService ) {
this.notifier = notifierService;
}
}
Show notifications
Showing a notification is simple - all your need is a type, and a message to be displayed. For example:
this.notifier.notify( 'success', 'You are awesome! I mean it!' );
You can further pass in a notification ID as the third (optional) argument. Essentially, such a notification ID is nothing more but a
unique string tha can be used later on to gain access (and thus control) to this specific notification. For example:
this.notifier.notify( 'success', 'You are awesome! I mean it!', 'THAT_NOTIFICATION_ID' );
For example, you might want to define a notification ID if you know that, at some point in the future, you will need to remove this
exact notification.
The syntax above is actually just a shorthand version of the following:
this.notifier.show( {
type: 'success',
message: 'You are awesome! I mean it!',
id: 'THAT_NOTIFICATION_ID'
} );
Hide notifications
You can also hide notifications. To hide a specific notification - assuming you've defined a notification ID when creating it, simply
call:
this.notifier.hide( 'THAT_NOTIFICATION_ID' );
Furthermore, your can hide the newest notification by calling:
this.notifier.hideNewest();
Or, your could hide the oldest notification:
this.notifier.hideOldest();
And, of course, it's also possible to hide all visible notifications at once:
this.notifier.hideAll();
How to customize
From the beginning, the angular-notifier library has been written with customizability in mind. The idea is that angular-notifier
works the way your want it to, so that you can make it blend perfectly into the rest of your application. Still, the default configuration
should already provide a great User Experience.
Keep in mind that angular-notifier can be configured only once - which is at the time you import the NotifierModule
into your root
(app) module.
Position
With the position
property you can define where exactly notifications will appear on the screen:
position: {
horizontal: {
position: 'left',
distance: 12
},
vertical: {
position: 'bottom',
distance: 12
gap: 10
}
}
Theme
With the theme
property you can change the overall look and feel of your notifications:
theme: 'material';
Theming in detail
Well, how does theming actually work? In the end, the value set for the theme
property will be part of a class added to each notification
when being created. For example, using material
as the theme results in all notifications getting a class assigned named x-notifier__notification--material
.
Everyone - yes, I'm looking at you - can use this mechanism to write custom notification themes and apply them via the theme
property.
For example on how to create a theme from scratch, just take a look at the themes coming along with this library (as for now only the
material
theme).
Behaviour
With the behaviour
property you can define how notifications will behave in different situations:
behaviour: {
autoHide: 5000,
onClick: false,
onMouseover: 'pauseAutoHide',
showDismissButton: true,
stacking: 4
}
Animations
With the animations
property your can define whether and how exactly notification will be animated:
animations: {
enabled: true,
show: {
preset: 'slide',
speed: 300,
easing: 'ease'
},
hide: {
preset: 'fade',
speed: 300,
easing: 'ease',
offset: 50
},
shift: {
speed: 300,
easing: 'ease'
},
overlap: 150
}
In short -- the default configuration
To sum it up, the following is the default configuration (copy-paste-friendly):
const notifierDefaultOptions: NotifierOptions = {
position: {
horizontal: {
position: 'left',
distance: 12
},
vertical: {
position: 'bottom',
distance: 12,
gap: 10
}
},
theme: 'material',
behaviour: {
autoHide: 5000,
onClick: false,
onMouseover: 'pauseAutoHide',
showDismissButton: true,
stacking: 4
},
animations: {
enabled: true,
show: {
preset: 'slide',
speed: 300,
easing: 'ease'
},
hide: {
preset: 'fade',
speed: 300,
easing: 'ease',
offset: 50
},
shift: {
speed: 300,
easing: 'ease'
},
overlap: 150
}
};
What's next?
There is an endless number of features, enhancements, and optimizations that would be possible (and awesome to have) in the
angular-notifier library. Some ideas:
- Extended options for all - and even single - notifications
- Symbol for notifications (e.g. checkmark, cross, or even images)
- Custom buttons next to the close button (with callback functionality)
- Callback functions / observable streams for specific events / global events
- Enhanced stacking (e.g. negative values, document size as implicit stacking limit)
- Allowing the change of content from outside (e.g. while the notifications is still on-screen)
- Allow custom animation presets, configurable from outside (similar to that creating custom themes is possible)
- More themes coming along with angular-notifier (e.g. iOS style, MDL style, bootstrap style)
- HTML templates as notification content
- React on document size changes (full responsiveness)
- Pull Request Templates, Contributing Guidelines
- Refactor unit tests
You can't wait for one of these features? Or have some new ideas? Let me know by creating an issue. Contributions are of course welcomed at any time!
Or look at one of the alternative notification libraries for Angular. A great collection can be found
right here.
Creator
Dominique Müller