postcss-if-function

A PostCSS plugin for transforming CSS if() functions into native CSS @media and @supports rules at build time.

This plugin is part of the css-if-polyfill project and provides build-time transformation of conditional CSS, eliminating the need for runtime JavaScript processing when using only media() and supports() functions.

Input CSS:

.responsive {
	width: if(media(width <= 768px): 100%; else: 50%);
}

Expected Output:

.responsive {
	width: 50%;
}
@media (width <= 768px) {
	.responsive {
		width: 100%;
	}
}

Installation

npm install postcss-if-function postcss

Usage

PostCSS CLI

# Transform CSS using PostCSS CLI
npx postcss input.css --output output.css --use postcss-if-function

# With custom PostCSS config file
npx postcss input.css --output output.css --config postcss.config.js

Basic Programmatic Usage

// Named export (recommended)
import postcss from "postcss";
import { postcssIfFunction } from "postcss-if-function";

// Or default export (for compatibility)
import postcss from "postcss";
import postcssIfFunction from "postcss-if-function";

const css = `
.example {
  color: if(media(max-width: 768px): blue; else: red);
  font-size: if(supports(display: grid): 1.2rem; else: 1rem);
}
`;

const result = await postcss([postcssIfFunction()]).process(css, {
	from: undefined
});

console.log(result.css);

Output:

.example {
	color: red;
}
@media (max-width: 768px) {
	.example {
		color: blue;
	}
}
.example {
	font-size: 1rem;
}
@supports (display: grid) {
	.example {
		font-size: 1.2rem;
	}
}

With Options

const result = await postcss([
	postcssIfFunction({
		logTransformations: true,
		preserveOriginal: false,
		skipSelectors: [".no-transform"]
	})
]).process(css, { from: undefined });

With PostCSS Config File

// postcss.config.js
import { postcssIfFunction } from "postcss-if-function";

export default {
	plugins: [
		postcssIfFunction({
			logTransformations: process.env.NODE_ENV === "development"
		})
	]
};

With Popular PostCSS Tools

Vite

// vite.config.js
import { defineConfig } from "vite";
import { postcssIfFunction } from "postcss-if-function";

export default defineConfig({
	css: {
		postcss: {
			plugins: [
				postcssIfFunction({
					logTransformations: process.env.NODE_ENV === "development"
				})
			]
		}
	}
});

Webpack

// webpack.config.js
module.exports = {
	module: {
		rules: [
			{
				test: /\.css$/,
				use: [
					"style-loader",
					"css-loader",
					{
						loader: "postcss-loader",
						options: {
							postcssOptions: {
								plugins: [
									[
										"postcss-if-function",
										{
											logTransformations: true
										}
									]
								]
							}
						}
					}
				]
			}
		]
	}
};

Next.js

// next.config.js
module.exports = {
	experimental: {
		postcss: {
			plugins: {
				"postcss-if-function": {
					logTransformations: process.env.NODE_ENV === "development"
				}
			}
		}
	}
};

Options

| Option | Type | Default | Description | | -------------------- | ---------- | ------- | -------------------------------------------------------------------------- | | preserveOriginal | boolean | false | Whether to preserve original CSS alongside transformations (for debugging) | | logTransformations | boolean | false | Whether to log transformation statistics to console | | skipSelectors | string[] | [] | Array of selectors to skip transformation for |

Supported Transformations

Media Queries

Input CSS:

.responsive {
	width: if(media(width <= 768px): 100%; else: 50%);
}

Expected Output:

.responsive {
	width: 50%;
}
@media (width <= 768px) {
	.responsive {
		width: 100%;
	}
}

Feature Support Queries

Input CSS:

.grid {
	display: if(supports(display: grid): grid; else: block);
}

Expected Output:

.grid {
	display: block;
}
@supports (display: grid) {
	.grid {
		display: grid;
	}
}

Multiple Conditions

Input CSS:

.responsive {
	padding: if(
		media(width >= 1200px): 40px; media(width >= 768px): 30px;
			media(width >= 480px): 20px; else: 15px
	);
}

Expected Output:

.responsive {
	padding: 15px;
}
@media (width >= 480px) {
	.responsive {
		padding: 20px;
	}
}
@media (width >= 768px) {
	.responsive {
		padding: 30px;
	}
}
@media (width >= 1200px) {
	.responsive {
		padding: 40px;
	}
}

Limitations

• Style Functions Not Supported: This plugin only transforms media() and supports() functions. For style() functions (which depend on runtime DOM state), use the css-if-polyfill runtime (browser) library
• Static Analysis Only: The plugin performs static analysis and cannot handle dynamically generated CSS
• PostCSS Compatibility: Requires PostCSS 8.0.0 or higher

Integration with Runtime Polyfill

For complete CSS if() support including style() functions, combine this plugin with the runtime polyfill:

1. Use this PostCSS plugin for build-time transformation of media() and supports()
2. Use css-if-polyfill runtime for style() functions

<!-- For style() functions only -->
<script src="https://cdn.jsdelivr.net/npm/css-if-polyfill/dist/index.modern.js"></script>

Performance Considerations

This plugin is designed for optimal build-time performance, transforming CSS if() functions to native CSS without runtime overhead. However, there are some architectural considerations:

Current Implementation

• Double Parsing: The plugin currently parses CSS twice - once by PostCSS and once by the transformation engine
• String-based Transformation: The transformation engine outputs CSS strings that are re-parsed into PostCSS AST nodes

Future Optimization Opportunities

• Reduced CSS Code: We'll make use of CSS Nesting capabilities as soon as any of the browsers are EOL (#35).
• Direct AST Transformation: The transformation engine could be modified to output PostCSS AST nodes directly, eliminating the double parsing overhead
• Streaming Processing: For very large CSS files, streaming transformation could reduce memory usage

For most typical usage scenarios, the current performance is excellent and the double parsing overhead is negligible compared to the benefits of build-time transformation.

Contributing

See the main Contributing Guide for details on how to contribute to this project.

License

MIT © Maximilian Franzke

Related

• PostCSS - Tool for transforming CSS with JavaScript
• CSS Conditional Rules - MDN documentation for @media and @supports

Further solutions

• css-if-polyfill - Runtime polyfill for CSS if() functions
• lightningcss-plugin-if-function - Lightning CSS plugin for build-time transformation
• stylelint-config-if-function - Stylelint configuration for linting CSS if() usage