react-z-index

:globe_with_meridians: Easily manage global component z-index

Made with ❤ at @outlandish

Takes the pain out of managing component zIndex across your application! :heart_eyes:

Check out an example on JSBin.

Features

• Manage zIndex values in one place
• Dynamically set the zIndex of components
• Optionally warns you if a zIndex value is used more than once
• Component or decorator interface
• Add new zIndex values with ease
• Create zIndex values...
  • automatically; generate unique and ordered zIndex values, or
  • manually; define your own zIndex values entirely, or
  • both!

Note: react-z-index does not override stacking contexts.

Install

npm i --save react-z-index

yarn add react-z-index

Import

The library uses ES2015 features so should be used in conjunction with Babel and a bundler for use within the browser environment, e.g. Browserify or Webpack.

// ES2015
import ZIndex from 'react-z-index' // component, util
import { zIndex } from 'react-z-index' // decorator

// CommonJS
var ZIndex = require('react-z-index')
var zIndex = require('react-z-index/decorator')

API

ZIndex.setVars(vars[, opts])

Optionally initialise react-z-index with a map of names to zIndex values.

• vars {Object|Array} Map of names to zIndex values or array of names
• [opts.start] {Number} (optional) Start zIndex for generated values (default: 10)
• [opts.step] {Number} (optional) Generated index step (default: 10)
• [opts.warnDuplicate] {Boolean} (optional) Warn if zIndex value used more than once (default: true)

Vars are made available at ZIndex.vars, e.g. ZIndex.vars.Modal.

// Explicit zIndex values
ZIndex.setVars({
  Modal: 300,
  Overlay: 200,
  Dropdown: 100
})

// Generated zIndex values
// First element is highest, last element is lowest
// Define explicit indexes using array
ZIndex.setVars([
  'Modal', //=> 30
  'Overlay', //=> 20
  ['Dropdown', 15], //=> 15
  'Backdrop' //=> 10
])

// e.g. suppress duplicate zIndex warning
ZIndex.setVars([
  ['ErrorModal', 100],
  ['WarningModal', 100]
], {
  warnDuplicate: false
})

ZIndex.setVar(name, value)

Set a new zIndex value.

• name {String} Name of the value
• value {Number} zIndex integer

Vars should be treated as constants, so this cannot be used to update the value of a predefined var.

ZIndex.setVar('Modal', 400)

Component

Each component should use exactly one of the following props:

• index {String|Number|Function} Set zIndex explicitly, by reference to predefined value, or derive from props
• above {String|Number} Set the zIndex to be above the value
• below {String|Number} Set the zIndex to be below the value
• top {Boolean} Set the zIndex to be above all other ZIndex components
• bottom {Boolean} Set the zIndex to be below all other ZIndex components

Optional additional props:

• important {Boolean} Set the !important flag on zIndex style value
• disabled {Boolean} Removes the zIndex style if true

The component will throw if not exactly one of these is given.

Examples:

import ZIndex from 'react-z-index'

ZIndex.setVars({ Overlay: 100 })

// e.g. toggle component at top of document using "top", "important", "disabled"
<ZIndex top important disabled={this.props.display}>
  <Modal />
</ZIndex>

// e.g. place component at derived zIndex using "index"
<ZIndex index={(props) => props.modal.priority * 100}>
  <Modal />
</ZIndex>
  
// e.g. place component underneath something else using "below"
<ZIndex below={ZIndex.vars.Overlay}> // style['z-index'] => 99
  <Modal />
</ZIndex>

Decorator

@zIndex(value<String,Number,Function>) : Component

When value is...

• a Number, sets the zIndex of a component to a constant:

  @zIndex(100)

• a Function, derives the zIndex of a component from its props:

  @zIndex((props) => props.modal.priority * 100)

• a String, sets the zIndex of a component by reference to a predefined var:

  @zIndex(ZIndex.vars.Modal)

Returns a React component.

Example:

import { zIndex } from 'react-z-index'

@zIndex(ZIndex.vars.Modal)
return class Modal extends Component {
  render () {
    return (
      <div className='modal'>
        ...
      </div>
    )
  }
}

Style

If you would like to use only the map of zIndex values you can do that too.

import ZIndex from 'react-z-index'

// Inform lib of the value so we can pick it up 
// elsewhere in the app as ZIndex.vars.Modal
const zIndex = ZIndex.setVar('Modal', 100)

class Modal extends Component {
  render () {
    return (
      <div className='modal' style={{ zIndex }}></div>
    )
  }
}

Contributing

All pull requests and issues welcome!

If you're not sure how to contribute, check out Kent C. Dodds' great video tutorials on egghead.io!

Author & License

react-z-index was created by Sam Gluck and is released under the MIT license.