PostCSS Stack

A better way to manage z-indexes

Define the stack of components and PostCSS Stack will resolve the z-indexes for you instead of playing a game of z-index: 99999.

/* input */
.modal {
  z-index: stack('modal');
}

.tool-tip {
  z-index: stack('tool-tip');
}

.element-beneath {
  z-index: stack('beneath');
}

/* output */
.modal {
  z-index: 2;
}

.tool-tip {
  z-index: 1;
}

.element-beneath {
  z-index: -1;
}

Install

# npm
npm install --save-dev postcss postcss-stack

# or yarn
yarn add --dev postcss postcss-stack

Usage

Add it to your PostCSS work-flow, whatever way you choose to.

// Using a postcss.config.js
const stack = require('postcss-stack');

module.exports = {
  plugins: [
    stack({
      list: [
        { 'beneath': -1 },
        'application',
        'tool-tip',
        'modal'
      ]
    })
  ]
};

Then call the stack function with relevant item name in your css.

/* input */
.application {
  z-index: stack('application');
}

/* output */
.application {
  z-index: 0;
}

See tests for more examples.

Options

option	type	default	description
list	array or function	[]	Array of items in the stack or function returning array of items
increment	number	1	The increment value

list

The list of items that defines the stack. An item can either be explicitly defined by a name key and z-index value or by a name string that will have it's z-index auto-generated.

stack({
  list: [
    { 'explicit': -10 }, // stack('explicit') => z-index: -10
    'auto', // stack('auto') => z-index: 0
    'generated', // stack('generated') => z-index: 1
  ]
});

By default it's ordered by the order of the array, but you can use Array.prototype.reverse() to better visualize how the stack is set.

stack({
  list: [
    { 'beneath': -1 }, // z-index: -1
    'application', // z-index: 0
    'tool-tip',  // z-index: 1
    'modal'  // z-index: 2
  ]
});

// Reversed
stack({
  list: [
    'modal' // z-index: 2
    'tool-tip', // z-index: 1
    'application', // z-index: 0
    { 'beneath': -1 }, // z-index: -1
  ].reverse();
});

increment

Allows a increment value to be set. For example if increment: 100, the output of our example would be:

.modal {
  z-index: 200;
}

.tool-tip {
  z-index: 100;
}

.element-beneath {
  z-index: -1;
}

Stacking Context

Remember that stacking context is relative to the parent, so if you have a parent element that is z-index: 2 and a child of z-index: 1, the child will not be below the parent but instead relative to any other stacking context of that parent.

For more information on stacking context, MDN has a good overview.

License