react-meerkat

Alerts for React

Demo

Installation

$ npm install --save react-meerkat

Templates

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

• Basic
• Dark

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

To get started, try installing the basic one:

$ npm install --save react-meerkat react-meerkat-template-basic

Peer dependencies

This package expect the following peer dependencies:

"prop-types": "^15.6.0"
"react": "^16.3.0"
"react-dom": "^16.3.0"
"react-transition-group": "^2.3.0"

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:

// index.js
import React, { Component } from 'react'
import { render } from 'react-dom'
import { Provider as AlertProvider } from 'react-meerkat'
import AlertTemplate from 'react-meerkat-template-basic'
import App from './App'

// optional cofiguration
const options = {
  position: 'bottom center',
  timeout: 5000,
  offset: '30px',
  transition: 'scale'
}

class Root extends Component  {
  render () {
    return (
      <AlertProvider template={AlertTemplate} {...options}>
        <App />
      </AlertProvider>
    )
  }
}

render(<Root />, document.getElementById('root'))

Then you wrap the components that you want to be able to show alerts:

// App.js
import React, { Component } from 'react'
import { withAlert } from 'react-meerkat'

class App extends Component  {
  render () {
    return (
      <button
        onClick={() => {
          this.props.alert.show('Oh look, an alert!')
        }}
      >
        Show Alert
      </button>
    )
  }
}

export default withAlert(App)

And that's it!

You can also use it with a render props API:

// App.js
import React, { Component } from 'react'
import { Alert } from 'react-meerkat'

class App extends Component  {
  render () {
    return (
      <Alert>
        {alert => (
          <button
            onClick={() => {
              alert.show('Oh look, an alert!')
            }}
          >
            Show Alert
          </button>
        )}
      </Alert>
    )
  }
}

export default App

Options

You can pass the following options as props to Provider:

offset: PropTypes.string // the margin of each alert
position: PropTypes.oneOf([
  'top left',
  'top right',
  'top center',
  'bottom left',
  'bottom right',
  'bottom center'
]) // the position of the alerts in the page
timeout: PropTypes.number // timeout to alert remove itself, if  set to 0 it never removes itself
type: PropTypes.oneOf(['info', 'success', 'error']) // the default alert type used when calling this.props.alert.show
transition: PropTypes.oneOf(['fade', 'scale']) // the transition animation
zIndex: PropTypes.number // the z-index of alerts
template: PropTypes.oneOfType([PropTypes.element, PropTypes.func]).isRequired // the alert template to be used

Here's the defaults:

offset: '10px'
position: 'top center'
timeout: 0
type: 'info'
transition: 'fade',
zIndex: 100

Those options will be applied to all alerts.

API

When you wrap a component using withAlert you receive the alert prop. Here's all you can do with it:

// show
const alert = this.props.alert.show('Some message', {
  timeout: 2000 , // custom timeout just for this one alert
  type: 'success',
  onOpen: () => { console.log('hey') }, // callback that will be executed after this alert open
  onClose: () => { console.log('closed') } // callback that will be executed after this alert is removed
})

// info
// just an alias to this.props.alert.show(msg, { type: 'info' })
const alert = this.props.alert.info('Some info', {
  timeout: 2000 , // custom timeout just for this one alert
  onOpen: () => { console.log('hey') }, // callback that will be executed after this alert open
  onClose: () => { console.log('closed') } // callback that will be executed after this alert is removed
})

// success
// just an alias to this.props.alert.show(msg, { type: 'success' })
const alert = this.props.alert.success('Some success', {
  timeout: 2000 , // custom timeout just for this one alert
  onOpen: () => { console.log('hey') }, // callback that will be executed after this alert open
  onClose: () => { console.log('closed') } // callback that will be executed after this alert is removed
})

// error
// just an alias to this.props.alert.show(msg, { type: 'error' })
const alert = this.props.alert.error('Some error', {
  timeout: 2000 , // custom timeout just for this one alert
  onOpen: () => { console.log('hey') }, // callback that will be executed after this alert open
  onClose: () => { console.log('closed') } // callback that will be executed after this alert is removed
})

// remove
// use it to remove an alert programmatically
this.props.alert.remove(alert)

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:

// index.js
import React, { Component } from 'react'
import { render } from 'react-dom'
import { Provider as AlertProvider } from 'react-meerkat'
import App from './App'

class AlertTemplate extends Component {
  render () {
    // the style contains only the margin given as offset
    // options contains all alert given options
    // message is the alert message...
    // close is a function that closes the alert
    const { style, options, message, close } = this.props

    return (
      <div style={style}>
        {options.type === 'info' && '!'}
        {options.type === 'success' && ':)'}
        {options.type === 'error' && ':('}
        {message}
        <button onClick={close}>X</button>
      </div>
    )
  }
}

class Root extends Component  {
  render () {
    return (
      <AlertProvider template={AlertTemplate}>
        <App />
      </AlertProvider>
    )
  }
}

render(<Root />, document.getElementById('root'))

Easy, right?

Using a component as a message

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

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

Special thank-you

react-meerkat is a fork of react-alert, written by schiehll. Thank you for all the work you put in.