react-notifications-component

A delightful, easy to use and highly configurable component to help you notify your users out of the box. No messy setup, just beautiful notifications!

:exclamation: :exclamation: :exclamation: As of version 3.3.0 react-notifications-component no longer uses default export. Rely on this import instead

import { ReactNotifications, Store } from 'react-notifications-component'

Demo

https://teodosii.github.io/react-notifications-component/

Features

• Touch support
• Responsive notifications
• Standard notification types
• Custom notification types
• Custom notification content
• Dismissable (touch, click, timeout)
• Customizable transitions
• Small library

Getting started

npm install react-notifications-component

Development

First build the library

npm run build:library:dev

then run the webpack server to see the app running

npm run start

Usage

#

Import react-notifications-component

import { ReactNotifications } from 'react-notifications-component'

Import the CSS theme

import 'react-notifications-component/dist/theme.css'

SASS

SASS files are located in react-notifications-component/dist/scss

Render react-notifications-component at the top of your application so that it does not conflict with other absolutely positioned DOM elements.

const App = () => {
  return (
    <div className="app-container">
      <ReactNotifications />
      <Application />
    </div>
  )
};

Import Store where needed - will be used to access addNotification and removeNotification API methods

import { Store } from 'react-notifications-component';

Then call addNotification and watch the magic happens

Store.addNotification({
  title: "Wonderful!",
  message: "teodosii@react-notifications-component",
  type: "success",
  insert: "top",
  container: "top-right",
  animationIn: ["animate__animated", "animate__fadeIn"],
  animationOut: ["animate__animated", "animate__fadeOut"],
  dismiss: {
    duration: 5000,
    onScreen: true
  }
});

Voila!

Note: We rely on animate.css in this example as animate__fadeIn and animate__fadeOut are part of animate.css. We recommend using it as it's an excellent animation library, but you're not forced to. If you prefer you may also use your custom animations as long as they're valid CSS animations.

Note: animate.css latest version (v4) has breaking changes. It introduces animate__ prefix so that existing classes don't clash. If you still would like to use classes without prefix you can import animate.css/animate.compat.css

// preferred way to import (from `v4`). Uses `animate__` prefix.
import 'animate.css/animate.min.css';

// Alternate way to use classes without prefix like `animated fadeIn`
import 'animate.css/animate.compat.css'

In the examples, we will be using classes with animate__ prefix, which is the default behaviour of latest v4 version of animate.css.

For more info on how to use animate.css, please refer to animate.css docs

API

Store.addNotification(options)

Render a new notification. Method returns a unique id for the rendered notification. Supplied options are internally validated and an exception will be thrown if validation fails.

Store.removeNotification(id)

Manually remove a notification by id.

Examples

In the following examples for brevity some options will not be mentioned. Strictly focusing on the needed options to present each example. For reference, we will be using Object spread operator on a notification object to have non relevant fields included as well.

notification = {
  title: "Wonderful!",
  message: "Configurable",
  type: "success",
  insert: "top",
  container: "top-right",
  animationIn: ["animate__animated animate__fadeIn"], // `animate.css v4` classes
  animationOut: ["animate__animated animate__fadeOut"] // `animate.css v4` classes
};

Notification container

You have in total 6 containers for desktop and 2 for mobile, if component is set to be responsive. List of containers:

• top-left
• top-right
• top-center
• center
• bottom-left
• bottom-right
• bottom-center

Store.addNotification({
  ...notification,
  container: 'top-right'
})

Will position the notification in top right of the screen.

Notification type

List of types:

• success
• danger
• info
• default
• warning

Store.addNotification({
  ...notification,
  type: 'danger'
})

Will trigger a danger notification.

Animating

Store.addNotification({
  ...notification, 
  animationIn: ['animate__animated animate__fadeIn'], // `animate.css v4` classes
  animationOut: ['animate__animated animate__fadeOut'] // `animate.css v4` classes
})

animationIn and animationOut rely on CSS classes that toggle animations. On github pages we rely on animate.css, we suggest you to import that package and use their animations as they have plenty.

Note: Failing to have animations set properly will lead to bugs in some causes, as react-notifications-component relies on onAnimationEnd event to know when an animation has finished.

Dismiss notification automatically after timeout expires

Store.addNotification({
  ...notification,
  dismiss: {
    duration: 2000
  }
})

Dismiss notification automatically with the time left shown on UI

Store.addNotification({
  ...notification,
  dismiss: {
    duration: 2000,
    onScreen: true
  }
})

Subscribe to notification's removal

Easily subscribe to onRemoval by supplying callback as option to the notification object. Callback will get called after the removal animation finishes.

Store.addNotification({
  ...notification,
  onRemoval: (id, removedBy) => {
    ...
  }
})

Pause notification's timeout by hovering

Store.addNotification({
  ...notification,
  dismiss: {
    duration: 2000,
    pauseOnHover: true
  }
})

Change transition

Store.addNotification({
  ...notification,
  slidingExit: {
    duration: 800,
    timingFunction: 'ease-out',
    delay: 0
  }
})

slidingEnter, touchRevert and touchSlidingExit can all be configured in the same way, with the mention that touchSlidingExit has 2 transitions nested.

Store.addNotification({
  ...notification,
  touchSlidingExit: {
    swipe: {
      duration: 400,
      timingFunction: 'ease-out',
      delay: 0,
    },
    fade: {
      duration: 400,
      timingFunction: 'ease-out',
      delay: 0
    }
  }
})

Props

Options

Transition

Transition is used each time you define a transition.

Dismiss

Dismiss is used to describe how a notification should be dismissed.

Migration from v1

• Ref usage has been deprecated. Import Store from library and use it for adding and removing notifications
• touchSlidingBack has been renamed to touchRevert
• Default values for transitions have been slightly changed
• dismissIcon has been removed. Use showIcon instead. If you relly on customized close icon, then stick to custom content.
• dismiss supports now more options
• cubicBezier has been renamed to timingFunction
• Validators are now no longer included in the prod build, they are only included in the dev build. If you inspect the npm package you will see that the component has 2 builds - dev and prod - and relies on ENV variable when importing.

License

MIT

Changelog

4.0.1

Changes

• Merged PR #156 on preventing onTransitionEnd to run multiple times
• Fixed full-bottom / full-top not being set width to 100%
• Fixed animated__ classes for a few examples on GH pages

4.0.0

Changes

• Use React 18.0.1

3.4.1

Changes

• Set rnc__notification class on the rendered notification

3.4.0

Fixes

• Fixed webpack self export
• Fixed Store removal functions not triggering DOM removal #140

Changes

• Pass notificationConfig as parameter when using custom component

3.3.0

Changes

• Removed default export - You now need to import ReactNotifications (and Store) instead of the default import
• All typescript declarations are now included in the dist folder

3.2.0

Fixes

• Fixed TS declarations #124
• Namespaced CSS modules under rnc_* #123
• Custom width for center containers #108

Breaking Changes

• Namespaced CSS modules

3.0.5

Fixes

• Fix TS not exporting all interfaces
• Bump React to 17.0.1

3.0.0

Changes

• TS support
• Added full-sized containers for top and bottom
• Changed SASS style to match BEM - breaking change
• Limit center containers to 350px
• Allow dynamic expansion of containers based on each notification's width
• Adedd new API call removeAllNotifications
• Removed prop-types package, props are now defaulted internally

Fixes

• 82, #69, #67, #65, #63, #61

2.4.1

Changes

• Merged pull request #76 - Add option to override default values
• Updated packages

2.4.0

Fixes

• Fixed issue #56 - Removed random generator for id, instead rely on counter property from store as id
• Fixed #52 - Swipe was not working properly

Changes

• Implemented #46 - Added center container. Did some changes to top and bottom containers as Chrome blurred content at the beginning of the animation due to the transform property.
• Changed notifications to take 100% width of the container instead of auto.

2.3.0

Fixes

• Fixed issue #52 - Swipe not working on touch devices
• Fixes issue #42 - title and message accept now custom content (a React node or a functional component)
• Fixed issue #41 - pauseOnHover was not taken into consideration when used together with content

Changes

• Changed containers to have fixed width of 325px instead of auto which had different results across different test cases. Mobile containers have not changed, they're full width as before.

2.2.0

Fixes

• Merged pull request #31 to pass className to component
• Fixed issue #33 - Unsubscribe from resize once component was unmounted
• Fixed issue #35 - content now gets id supplied as a prop

2.1.0

Breaking changes

• Removed prop onNotificationRemoval as it was rather hard to know which particular notification has been removed.

Improvements

• Added option onRemoval directly to the notification object. Each notification will have its own onRemoval, making it easier to track removals.
• Removed style-loader from webpack dev config

2.0.0

Breaking changes

• Ref usage has been deprecated. Import store from library and use it for adding and removing notifications
• touchSlidingBack has been renamed to touchRevert
• dismissIcon has been removed. Use showIcon instead. If you rely on customized close icon, then stick to custom content.
• cubicBezier has been renamed to timingFunction

Improvements

• Validators are now no longer included in the prod build, they are only included in the dev build. If you inspect the npm package you will see that the component has 2 builds - dev and prod - and relies on ENV variable when importing.
• Default values for transitions have been slightly changed
• dismiss supports now more options

Removed

• Test coverage has been removed as library's been almost fully rewritten in 2.0.0

1.0.0

Stable and production ready release of react-notifications-component