react-z-index
🌐 Easily manage global component z-index
Made with ❤ at @outlandish
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
// CommonJSvar ZIndex = var zIndex =
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 valuesZIndex // Generated zIndex values// First element is highest, last element is lowest// Define explicit indexes using arrayZIndex // e.g. suppress duplicate zIndex warningZIndex
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
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:
ZIndex // e.g. toggle component at top of document using "top", "important", "disabled"<ZIndex top important disabled=thispropsdisplay> <Modal /></ZIndex> // e.g. place component at derived zIndex using "index"<ZIndex index= propsmodalpriority * 100> <Modal /></ZIndex> // e.g. place component underneath something else using "below"<ZIndex below=ZIndexvarsOverlay> // 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:
@return { return <div className='modal'> ... </div> }
Style
If you would like to use only the map of zIndex values you can do that too.
// Inform lib of the value so we can pick it up // elsewhere in the app as ZIndex.vars.Modalconst zIndex = ZIndex { 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.