react-alert

alerts for React

Demo

Installation

1$ npm install --save react-alert

Templates

You can provide your own alert template if you need to. Otherwise you can just plug in one of the following:

• Basic
• Dark
• Material UI

Feel free to submit a PR with the link for your own template.

To get started, try installing the basic one:

1$ npm install --save react-alert react-alert-template-basic

Peer dependencies

This package expect the following peer dependencies:

  "react": "^16.8.1"
  "react-dom": "^16.8.1"

So make sure that you have those installed too!

Usage

First you have to wrap your app with the Provider giving it the alert template and optionally some options:

1// index.js
2import React from 'react'
3import { render } from 'react-dom'
4import { transitions, positions, Provider as AlertProvider } from 'react-alert'
5import AlertTemplate from 'react-alert-template-basic'
6import App from './App'
7
8// optional configuration
9const options = {
10  // you can also just use 'bottom center'
11  position: positions.BOTTOM_CENTER,
12  timeout: 5000,
13  offset: '30px',
14  // you can also just use 'scale'
15  transition: transitions.SCALE
16}
17
18const Root = () => (
19  <AlertProvider template={AlertTemplate} {...options}>
20    <App />
21  </AlertProvider>
22)
23
24render(<Root />, document.getElementById('root'))

Then import the useAlert hook to be able to show alerts:

1// App.js
2import React from 'react'
3import { useAlert } from 'react-alert'
4
5const App = () => {
6  const alert = useAlert()
7
8  return (
9    <button
10      onClick={() => {
11        alert.show('Oh look, an alert!')
12      }}
13    >
14      Show Alert
15    </button>
16  )
17}
18
19export default App

And that's it!

You can also use it with a HOC:

1import React from 'react'
2import { withAlert } from 'react-alert'
3
4const App = ({ alert }) => (
5  <button
6    onClick={() => {
7      alert.show('Oh look, an alert!')
8    }}
9  >
10    Show Alert
11  </button>
12)
13
14export default withAlert()(App)

Options

You can pass the following options as props to Provider:

1offset: PropTypes.string // the margin of each alert
2position: PropTypes.oneOf([
3  'top left',
4  'top right',
5  'top center',
6  'middle left',
7  'middle',
8  'middle right',
9  'bottom left',
10  'bottom right',
11  'bottom center'
12]) // the position of the alerts in the page
13timeout: PropTypes.number // timeout to alert remove itself, if  set to 0 it never removes itself
14type: PropTypes.oneOf(['info', 'success', 'error']) // the default alert type used when calling this.props.alert.show
15transition: PropTypes.oneOf(['fade', 'scale']) // the transition animation
16containerStyle: PropTypes.Object // style to be applied in the alerts container
17template: PropTypes.oneOfType([PropTypes.element, PropTypes.func]).isRequired // the alert template to be used

Note that the position, type and transition strings are available as constants which can be imported the next way:

1import { positions, transitions, types } from 'react-alert'

and have such values:

1export const positions = {
2  TOP_LEFT: 'top left',
3  TOP_CENTER: 'top center',
4  TOP_RIGHT: 'top right',
5  MIDDLE_LEFT: 'middle left',
6  MIDDLE: 'middle',
7  MIDDLE_RIGHT: 'middle right',
8  BOTTOM_LEFT: 'bottom left',
9  BOTTOM_CENTER: 'bottom center',
10  BOTTOM_RIGHT: 'bottom right'
11}
12
13export const types = {
14  INFO: 'info',
15  SUCCESS: 'success',
16  ERROR: 'error'
17}
18
19export const transitions = {
20  FADE: 'fade',
21  SCALE: 'scale'
22}

Here's the defaults:

1offset: '10px'
2position: positions.TOP_CENTER
3timeout: 0
4type: types.INFO
5transition: transitions.FADE,
6containerStyle: {
7  zIndex: 100
8}

Those options will be applied to all alerts (please, also have a look at edge-cases)

Api

After getting the alert with the useAlert hook, this is what you can do with it:

1// show
2const alert = alert.show('Some message', {
3  timeout: 2000, // custom timeout just for this one alert
4  type: 'success',
5  onOpen: () => {
6    console.log('hey')
7  }, // callback that will be executed after this alert open
8  onClose: () => {
9    console.log('closed')
10  } // callback that will be executed after this alert is removed
11})
12
13// info
14// just an alias to alert.show(msg, { type: 'info' })
15const alert = alert.info('Some info', {
16  timeout: 2000, // custom timeout just for this one alert
17  onOpen: () => {
18    console.log('hey')
19  }, // callback that will be executed after this alert open
20  onClose: () => {
21    console.log('closed')
22  } // callback that will be executed after this alert is removed
23})
24
25// success
26// just an alias to alert.show(msg, { type: 'success' })
27const alert = alert.success('Some success', {
28  timeout: 2000, // custom timeout just for this one alert
29  onOpen: () => {
30    console.log('hey')
31  }, // callback that will be executed after this alert open
32  onClose: () => {
33    console.log('closed')
34  } // callback that will be executed after this alert is removed
35})
36
37// error
38// just an alias to alert.show(msg, { type: 'error' })
39const alert = alert.error('Some error', {
40  timeout: 2000, // custom timeout just for this one alert
41  onOpen: () => {
42    console.log('hey')
43  }, // callback that will be executed after this alert open
44  onClose: () => {
45    console.log('closed')
46  } // callback that will be executed after this alert is removed
47})
48
49// remove
50// use it to remove an alert programmatically
51alert.remove(alert)
52
53// removeAll
54// use it to remove all alerts programmatically
55alert.removeAll()

Using a custom alert template

If you ever need to have an alert just the way you want, you can provide your own template! Here's a simple example:

1import React from 'react'
2import { render } from 'react-dom'
3import { Provider as AlertProvider } from 'react-alert'
4import App from './App'
5
6// the style contains only the margin given as offset
7// options contains all alert given options
8// message is the alert message
9// close is a function that closes the alert
10const AlertTemplate = ({ style, options, message, close }) => (
11  <div style={style}>
12    {options.type === 'info' && '!'}
13    {options.type === 'success' && ':)'}
14    {options.type === 'error' && ':('}
15    {message}
16    <button onClick={close}>X</button>
17  </div>
18)
19
20const Root = () => (
21  <AlertProvider template={AlertTemplate}>
22    <App />
23  </AlertProvider>
24)
25
26render(<Root />, document.getElementById('root'))

Easy, right?

Using a component as a message

You can also pass in a component as a message, like this:

1alert.show(<div style={{ color: 'blue' }}>Some Message</div>)

Showing alerts in different positions at the same time

First of all, if have a need to separate the logic of showing alerts in different positions at the same time it is possible to use multiple AlertProviders in one project and nest them across the DOM tree. Also you can use different Contexts to get the references to each type of alert separately.

1import React, { createContext } from 'react'
2import { render } from 'react-dom'
3import { useAlert, positions, Provider as AlertProvider } from 'react-alert'
4import AlertTemplate from 'react-alert-template-basic'
5
6const TopRightAlertContext = createContext()
7
8const App = () => {
9  const alert = useAlert()
10  const topRightAlert = useAlert(TopRightAlertContext)
11
12  return (
13    <div>
14      <button onClick={() => alert.show('Oh look, an alert!')}>
15        Show Alert
16      </button>
17      <button
18        onClick={() =>
19          topRightAlert.show('Oh look, an alert in the top right corner!')
20        }
21      >
22        Show Top Right Alert
23      </button>
24    </div>
25  )
26}
27
28const Root = () => (
29  <AlertProvider template={AlertTemplate}>
30    <AlertProvider
31      template={AlertTemplate}
32      position={positions.TOP_RIGHT}
33      context={TopRightAlertContext}
34    >
35      <App />
36    </AlertProvider>
37  </AlertProvider>
38)
39
40render(<Root />, document.getElementById('root'))

Another use case is when you don't want to nest a couple of AlertProviders because it will somehow complicate management of alerts (for example when you need to show alerts in more than three different positions).

In this case you can pass the position directly to the alert. The alerts without individual position property will take it from the Provider. Instead, passing the position to methods show, success, info, error will overlap the Provider's position.

Passing the property position will look like this:

1alert.show('Oh look, an alert!', { position: positions.BOTTOM_LEFT })

An example of showing alerts simultaneously in three different positions:

1import React from 'react'
2import { render } from 'react-dom'
3import {
4  Provider as AlertProvider,
5  useAlert,
6  positions,
7  transitions
8} from 'react-alert'
9import AlertTemplate from 'react-alert-template-basic'
10
11const alertOptions = {
12  offset: '25px',
13  timeout: 3000,
14  transition: transitions.SCALE
15}
16
17const App = () => {
18  const alert = useAlert()
19
20  const showAlert = () => {
21    alert.show('Oh look, an alert!', { position: positions.BOTTOM_LEFT }) //alert will be shown in bottom left
22    alert.show('Oh look, an alert!', { position: positions.BOTTOM_RIGHT }) //alert will be shown in bottom right
23    alert.show('Oh look, an alert!') //alert will use the Provider's position `top right`
24  }
25
26  return <button onClick={showAlert}>Show Alert</button>
27}
28
29const Root = () => (
30  <AlertProvider template={AlertTemplate}>
31    <AlertProvider
32      template={AlertTemplate}
33      position={positions.TOP_RIGHT} //default position for all alerts without individual position
34      {...alertOptions}
35    >
36      <App />
37    </AlertProvider>
38  </AlertProvider>
39)
40
41render(<Root />, document.getElementById('root'))