OrcaXS/postcss-easy-z

PostCSS plugin to organize z-indices

PostCSS Easy Z

PostCSS plugin to organize z-indices by declaring relations between them.

z-stack

You can stack your CSS variables for z-indices with z-stack. Each new variable will be positioned over the previous:

:root {
  --z-content: z-stack();
  --z-header: z-stack();
  --z-popup: z-stack();
}

/* Output */
:root {
  --z-content: 1;
  --z-header: calc(var(--z-content) + 1);
  --z-popup: calc(var(--z-header) + 1);
}

Then just use these variables as usual:

.content {
  z-index: var(--z-content);
}

.header {
  z-index: var(--z-header);
}

.popup {
  z-index: var(--z-popup);
}

You can provide starting value for the stack:

:root {
  --z-content: z-stack(10);
  --z-header: z-stack();
}

/* Output */
:root {
  --z-content: 10;
  --z-header: calc(var(--z-content) + 1);
}

Stack is isolated by selector:

.a {
  --z-a1: z-stack();
  --z-a2: z-stack();
}

.b {
  --z-b1: z-stack();
  --z-b2: z-stack();
}

/* Output */
.a {
  --z-a1: 1;
  --z-a2: calc(var(--z-a1) + 1);
}

.b {
  --z-b1: 1;
  --z-b2: calc(var(--z-b1) + 1);
}

z-over and z-under

You can also explicitly describe relations between z-indices with z-over and z-under:

.overContent {
  z-index: z-over(var(--z-content));
}

.underHeader {
  z-index: z-under(var(--z-header));
}

/* Output */
.overContent {
  z-index: calc(var(--z-content) + 1);
}

.underHeader {
  z-index: calc(var(--z-header) - 1);
}

Installation

Step 1: Install plugin:

npm install --save-dev postcss postcss-easy-z

Step 2: Check you project for existed PostCSS config: postcss.config.js in the project root, "postcss" section in package.json or postcss in bundle config.

If you do not use PostCSS, add it according to official docs and set this plugin in settings.

Step 3: Add the plugin to plugins list:

module.exports = {
  plugins: [
+   require('postcss-easy-z'),
    require('autoprefixer')
  ]
}

Linting

To enforce usage of variables for z-index property add stylelint-declaration-strict-value to stylelint config:

module.exports = {
  plugins: ['stylelint-declaration-strict-value'],
  rules: {
    'scale-unlimited/declaration-strict-value': [
      'z-index',
      {
        ignoreValues: ['initial', -1, 0, 1],
      },
    ],
  },
}