React-awesome-notifications
A beautiful fully customizable React + Redux notification System built with styled-components
Table of contents
Demo
Check out the demo
Installation
using npm
npm install react-awesome-notifications --save
using yarn
yarn add react-awesome-notifications
Integration
Follow this 4 steps to integrate react-awesome-notifications to your application.
NotificationsSystem
React component
Integrate Render this component at the root of your web application to avoid position conflicts.
;;{return<div><NotificationsSystem /></div>;}
thunk
middleware and add notifications reducer to Redux store
Apply - Since react-awesome-notifications use thunk async actions creator, you must apply
thunk
middleware from redux-thunk to your Redux store. Install it withnpm install --save redux-thunk
. - Add notifications reducer as
notifications
to your root reducer.
;;;;const reducers =;const store = ;
notice: reducer must be mounted as notifications
Usage
In a React component
If you are not familiar with react-redux library or the way to connect a React component with a Redux store, I recommend you to read Redux documentation - Usage with React to understand this example.
;;// 1. we import `addNotification` (thunk action creator);{superprops;// 4. don't forget to bind methodthis_onClick = this_onClick;}{const addNotification = thisprops;// 3. we use `addNotification` to create a notification;}{return<div>// 5. we notify user when he click on the button<button onClick=this_onClick>Add a notification</button></div>;}// 2. we map dispatch to props `addNotification` async action creator// here we use a shortcut instead of passing a `mapDispathToProps` functionnull addNotificationMyComponent;
In a Redux async action creator
If you are not familiar with async actions creator, I recommend you to read Redux documentation - Async actions to understand this example.
// 1. we import `notify` (thunk action creator);// we add a notification to inform user about// state of his request (success or failure)const sendResetPasswordLink = {axios;};};
API Documentation
Objects
Notification
Property | Type | Default | Description |
---|---|---|---|
id | String or Number | ID of the notification. If not provided during creation, will be generated automatically using the universal id. | |
title | String | Title of the notification | |
message | String | Message of the notification | |
level | String | primary | level of the notification, available options : primary, info, success, warning, error. |
position | String | tr | Position of the notification, available options : tc , tl , tr , bc , br , bl . |
dismissible | Boolean | true | Define if a notification is dismissible by clicking on it |
dismissAfter | Number | 5000 | Time before the notification disappear (ms). Paused when mouse is hovering the notification. 0: infinite. |
closeButton | Boolean | false | Display a close button if it is dismissible |
buttons | Array | Array of button objects. | |
onMounted | Function | Function executed at component lifecycle : componentDidMount |
|
onUnmounted | Function | Function executed at component lifecycle : componentWillUnmount |
|
allowHTML | Boolean | false | Allow HTML in title and message of the notification |
extendStyles | Object | add custom styles to the notification see. ExtendStyles. |
Notification button
Property | Type | Default | Description |
---|---|---|---|
label | String | Title of the button | |
action | Function | Function executed when user click on it |
ExtendStyles
Property | Type | Default | Description |
---|---|---|---|
notificationWrapper | String | Add custom styles for the notification wrapper | |
notificationTitle | String | Add custom styles for the notification title | |
notificationMessage | String | Add custom styles for the notification message | |
notificationButtonsContainer | String | Add custom styles for the notification buttons container | |
notificationButton | String | Add custom styles for the notification button |
Action creators
Update or create a notification
Updates a notification if it does exist or creates it. It returns the notification just updated or created. You basically want to use this function all the time to update and create notifications.
Syntax
;
Parameters
Parameter | Type | Description |
---|---|---|
notification | Object | A notification object |
Example
// add a notificationlet notif =;// simulate file upload;
Create a notification
Creates a notification and returns it.
Syntax
;
Parameters
Parameter | Type | Description |
---|---|---|
notification | Object | A notification object |
Example
const notif =;console;/*{"id":1463345312016,"title":"Welcome on demo!","message":"Hey buddy, here you can see what you can do with it.","position":"br","level":"info","dismissAfter":10000,"dismissible":false,"buttons":[{"label":"OK",}]}*/
Update a notification
Updates a notification and returns it. If the notification has been removed, it will not display it again.
Syntax
;
Parameters
Parameter | Type | Description |
---|---|---|
notification | Object | A notification object |
Example
let notif =;// simulate file upload;
Remove a notification
Removes a notification.
Syntax
;
Parameters
Parameter | Type | Description |
---|---|---|
id | String or Number | ID of the notification |
Remove all notifications
Removes all notifications.
Syntax
;
Notifications system component
Property | Type | Default | Description |
---|---|---|---|
filter | Function | null | Filter notifications to display. Can be useful to display some notifications with another component, like modal notifications or banner notifications. |
Example
notif.style !== 'banner'}/>
Customize styling
you can add custom styles using ExtendStyles property . because this package uses styled components for apply styles to the final ui so you can use the power of styled components.
ExtendStyles property
Example usage of the;let not =id: 123title: 'my title'message: 'my message'buttons:label: 'submit'// custom stylesextendStyles:// customize styles for the notification wrapper// features: & parent placeholder, nesting, nesting classes..., any feature of styled-componentsnotificationWrapper: `background-color: pink;padding: 20px;.notification-close-btn{.close-btn{padding: 10px;&:hover{color: red;}}}`notificationTitle: ``;notificationMessage: ``;notificationButtonsContainer: ``;notificationButton: ``;;
Final rendred markup
{title}{message}×{button.label}
Contributing guide
All kinds of contributions (enhancements, new features, stories, documentation & bugs reporting) are welcome.
Setting up your environment
# clone repository
https://github.com/zakariaharti/react-awesome-notifications.git
cd react-awesome-notifications
# install dependencies
** yarn **
yarn install
** npm **
npm install
# Launch demo at http://localhost:6006
npm start
Here is the list of the available npm scripts :
npm run <script> |
Description |
---|---|
start | Launch demo at http://localhost:6006 |
webpack | Compile and lint code using the development env |
lint | Lint javascript files of source folder (src ) |
test | Run tests with jest |
test:coverage | Run tests with jest and generate coverage report (HTML and LCOV) |
build | run build for production env |
storybook | start storybook server at http://localhost:6006 |
build-storybook | build stories and generate a static files ready for deployment |
Example :
npm run compile
Pull requests
All pull requests must be done on the master branch.
Before a pull request :
- Don't forget to update README or documentation if it's necessary
- Check code status with
npm run webpack
- Run tests with
npm run test
- If you made styles changes or any changes related to user interfaces, launch demo with
npm start
to check the result in the browser. Check it on all possible browsers that you have. (Precise the list in the PR)
License
React-awesome-notifications is under MIT License