Nocturnal Pajama Mutants

    react-z-index

    3.0.0 • Public • Published

    react-z-index

    🌐 Easily manage global component z-index

    Made with ❤ at @outlandish

    npm version

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

    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.

    Install

    npm i react-z-index

    DownloadsWeekly Downloads

    12

    Version

    3.0.0

    License

    MIT

    Unpacked Size

    20 kB

    Total Files

    7

    Last publish

    Collaborators

    • sdgluck