PostCSS JavaScript Functions

4.0.2 · active · verified Sun Apr 19

postcss-functions is a PostCSS plugin that allows developers to expose JavaScript functions for direct invocation within CSS files during the build process. It enables dynamic value generation, complex calculations, and programmatic transformations of CSS properties, extending the capabilities of standard CSS. The current stable version is 4.0.2, maintaining compatibility with PostCSS v8.x. While release cadence isn't strictly defined, major version updates (like 4.0.0) indicate significant changes and active maintenance. Its key differentiator is providing a clean bridge between JavaScript logic and CSS styling without relying on preprocessors, allowing for highly customized and reusable CSS utility functions defined in JavaScript.

Common errors

```
TypeError: functions is not a function
```
cause The `postcss-functions` module is imported incorrectly, or the imported value is not invoked as a function.

fix Ensure you are using `import functions from 'postcss-functions';` and then calling it like `postcss().use(functions({ /* options */ }))`.
```
Error: Cannot find module 'postcss'
```
cause The `postcss` peer dependency is not installed.

fix Install `postcss` alongside `postcss-functions`: `npm install --save-dev postcss postcss-functions` or `yarn add --dev postcss postcss-functions`.
```
CSS: Unknown word at line X, column Y (e.g., `background-color: unknownFunction(arg);`)
```
cause A function called in CSS was not provided in the `functions` option or has a misspelled name.

fix Verify that the function name used in your CSS matches the key in the `functions` object passed to `postcss-functions`, and that the function object is correctly passed to the plugin.

Warnings

breaking The `glob` feature, which allowed specifying function files via glob patterns, was removed in version 4.0.0. This change reduces package size and dependencies.
Fix: Instead of using glob patterns, manually `import` your JavaScript function files into your PostCSS configuration file and pass them directly to the `functions` option object. You can use a separate globbing library like `fast-glob` in your build script if you still require dynamic loading.
gotcha Functions defined in the `functions` option must return valid CSS values. If a function returns an invalid or non-string value (e.g., `undefined`, `null`, a complex object), PostCSS may output unexpected CSS or throw an error during processing.
Fix: Ensure all exposed JavaScript functions explicitly return a string that represents a valid CSS value (e.g., 'red', '10px', 'rgb(0,0,0)').
gotcha Arguments passed to CSS functions from `postcss-functions` are always strings. If you expect numbers or booleans, you must explicitly parse them within your JavaScript function.
Fix: Inside your JavaScript function, use `parseFloat()`, `parseInt()`, `JSON.parse()`, or other conversion methods as needed to handle string arguments, e.g., `const value = parseFloat(arg);`.

Install

npm install postcss-functions npm
yarn add postcss-functions yarn
pnpm add postcss-functions pnpm

Imports

functions

wrong:

import { functions } from 'postcss-functions';

correct:

import functions from 'postcss-functions';

The plugin factory is a default export.

postcss
wrong:
```
const postcss = require('postcss');
```
correct:
```
import postcss from 'postcss';
```
This package, and PostCSS itself, are primarily used in ESM contexts for modern build setups. While CJS is possible, ESM is the idiomatic way for `postcss` v8+.
ProcessOptions
```
import { ProcessOptions } from 'postcss';
```
When using TypeScript, import types like `ProcessOptions` from the 'postcss' package for better type checking.

Quickstart

Demonstrates basic setup, defining custom JavaScript functions, and applying them within CSS using postcss-functions.

import fs from 'fs';
import postcss from 'postcss';
import functions from 'postcss-functions';

const inputCss = `
body {
  /* Example using a custom JS function */
  background-color: myCustomColor('darken', 'blue', 0.2);
}
.foo {
  color: darken(red, 0.1);
}
`;

// Define custom JavaScript functions to be exposed to PostCSS
const customFunctions = {
  myCustomColor: (mode, color, amount) => {
    // A more complex example, could involve external libraries
    if (mode === 'darken') {
      // Simplified darkening logic for demonstration
      return `rgba(0, 0, ${Math.floor(255 * (1 - parseFloat(amount)))}, 1)`;
    }
    return color;
  },
  darken: (value, frac) => {
    // Basic example of a function, similar to the README
    const darkenFactor = 1 - parseFloat(frac);
    // In a real scenario, use a color manipulation library
    // For demo, just return a string
    return `rgba(0, 0, ${Math.floor(255 * darkenFactor)}, 1)`;
  }
};

postcss()
  .use(functions({ functions: customFunctions }))
  .process(inputCss, { from: undefined })
  .then((result) => {
    console.log('Processed CSS:\n', result.css);
  })
  .catch((error) => {
    console.error('PostCSS processing failed:', error);
  });

view raw JSON →