PostCSS Conditional Values [][PostCSS]

npm install @csstools/postcss-conditional-values --save-dev

[PostCSS Conditional Values] lets you easily apply space toggle hacks with some syntactic sugar.

This plugin adds a non-standard function : csstools-if( else ) which acts as a ternary operator.

csstools-if(--a-variable else )

You control the outcome by setting --a-variable to true and false.

``css
.fancy-container {
--is-fancy: true;
}

.block {
color: csstools-if(--is-fancy pink else red);
}

/ becomes /

:root {
--is-fancy: ;
}

.fancy-container {
--is-fancy: initial;
}

.block {
--is-fancy--0: var(--is-fancy) red;
color: var(--is-fancy--0,pink);
}
`

For more information on how the trick works, you can read more on these articles:

- The CSS Custom Property Toggle Trick
- The -​-var: ; hack to toggle multiple values with one custom property

> [!IMPORTANT]
> [PostCSS Conditional Values] assumes to process your complete CSS bundle.
If your build tool processes files individually or processes files in parallel the output will be incorrect.
Using @csstools/postcss-bundler and @import statements is one way to make sure your CSS is bundled before it is processed by this plugin.

Usage

Add [PostCSS Conditional Values] to your project:

`bash
npm install postcss @csstools/postcss-conditional-values --save-dev
`

Use it as a [PostCSS] plugin:

`js
const postcss = require('postcss');
const postcssConditionalValues = require('@csstools/postcss-conditional-values');

postcss([
postcssConditionalValues(/ pluginOptions /)
]).process(YOUR_CSS /, processOptions /);
`

Options

$3

The functionName option allows you to set a custom alias for csstools-if.

`js
postcssConditionalValues({ functionName: 'if' })
`

`css
.fancy-container {
--is-fancy: true;
}

.block {
color: if(--is-fancy pink else red);
}

/ becomes /

:root {
--is-fancy: ;
}

.fancy-container {
--is-fancy: initial;
}

.block {
--is-fancy--0: var(--is-fancy) red;
color: var(--is-fancy--0,pink);
}
`

Syntax

$3

The csstools-if else function is used to declare which values must be used when a condition is true or false.

`css
color: csstools-if(--a-condition yellow else red);
`

`
csstools-if( else );
`

#### Stylelint

Stylelint is able to check for unknown property values.
Setting the correct configuration for this rule makes it possible to check even non-standard syntax.

`js
// Disallow unknown values for properties within declarations.
'declaration-property-value-no-unknown': [
true,
{
propertiesSyntax: {
color: '| csstools-if( <\'color\'> else <\'color\'> )',
'background-color': '| csstools-if( <\'background-color\'> else <\'background-color\'> )',
// ... more properties ...
},
},
],
`

$3

The true and false keywords are syntactic sugar for initial and .

`css
--a-condition: true;

/ becomes /

--a-condition: initial;
`

`css
--a-condition: false;

/ becomes /

--a-condition: ;
`

You can manually toggle the condition with initial and `.
This makes it possible to control the outcome of conditions with javascript, inline styles, ...

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test

[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/@csstools/postcss-conditional-values

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Conditional Values]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-conditional-values