@csstools/postcss-conditional-values v3.0.1

PostCSS Conditional Values

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 <value-when-true> else <value-when-false>)

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

.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 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:

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

Use it as a PostCSS plugin:

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

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

PostCSS Conditional Values runs in all Node environments, with special instructions for:

• Node
• PostCSS CLI
• PostCSS Load Config
• Webpack
• Next.js
• Gulp
• Grunt

Options

functionName

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

postcssConditionalValues({ functionName: 'if' })

.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

csstools-if else function

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

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

csstools-if(<custom-property-name> <declaration-value> else <declaration-value>);

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.

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

true and false keywords

The true and false keywords are syntactic sugar for initial and <space>.

--a-condition: true;

/* becomes */

--a-condition: initial;

--a-condition: false;

/* becomes */

--a-condition:  ;

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