postcss-functions

What is postcss-functions?

The postcss-functions npm package allows you to define and use custom functions within your CSS. This can be useful for a variety of tasks such as calculations, transformations, and dynamic value generation.

What are postcss-functions's main functionalities?

Custom Function Definitions

This feature allows you to define custom functions that can be used within your CSS. In the example, a function `calcWidth` is defined to add two pixel values together.

const postcss = require('postcss');
const functions = require('postcss-functions');

const css = `
  .example {
    width: calcWidth(100px, 50px);
  }
`;

const output = postcss([
  functions({
    functions: {
      calcWidth: (value1, value2) => {
        return parseFloat(value1) + parseFloat(value2) + 'px';
      }
    }
  })
]).process(css).css;

console.log(output);

Dynamic Value Generation

This feature allows you to generate dynamic values within your CSS. In the example, a function `dynamicColor` is defined to generate a random color.

const postcss = require('postcss');
const functions = require('postcss-functions');

const css = `
  .example {
    color: dynamicColor();
  }
`;

const output = postcss([
  functions({
    functions: {
      dynamicColor: () => {
        return '#'+Math.floor(Math.random()*16777215).toString(16);
      }
    }
  })
]).process(css).css;

console.log(output);

String Manipulation

This feature allows you to manipulate strings within your CSS. In the example, a function `appendText` is defined to concatenate two strings.

const postcss = require('postcss');
const functions = require('postcss-functions');

const css = `
  .example {
    content: appendText('Hello', ' World');
  }
`;

const output = postcss([
  functions({
    functions: {
      appendText: (text1, text2) => {
        return `'${text1 + text2}'`;
      }
    }
  })
]).process(css).css;

console.log(output);

Other packages similar to postcss-functions

postcss-mixins

The postcss-mixins package allows you to define and use mixins in your CSS. While it doesn't provide custom functions, it offers a way to reuse chunks of CSS code, which can achieve similar results in some cases.

postcss-simple-vars

The postcss-simple-vars package allows you to use variables in your CSS. While it doesn't provide custom functions, it can be used to store and reuse values, which can simplify complex CSS.

postcss-calc

The postcss-calc package allows you to reduce calc() references in your CSS. It doesn't provide custom functions but can simplify mathematical expressions in your CSS.

README

postcss-functions

PostCSS plugin for exposing JavaScript functions.

Installation

npm install --save-dev postcss postcss-functions

Usage

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

const options = {
	//options
};

const css = fs.readFileSync('input.css', 'utf8');

postcss()
  .use(functions(options))
  .process(css)
  .then((result) => {
    const output = result.css;
  });

Example of a function call:

body {
  prop: foobar();
}

Options

functions

Type: Object

An object containing functions. The function name will correspond with the object key.

Example:

import postcssFunctions from 'postcss-functions';
import { fromString, fromRgb } from 'css-color-converter';

function darken(value, frac) {
  const darken = 1 - parseFloat(frac);
  const rgba = fromString(value).toRgbaArray();
  const r = rgba[0] * darken;
  const g = rgba[1] * darken;
  const b = rgba[2] * darken;
  return fromRgb([r,g,b]).toHexString();
}

postcssFunctions({
  functions: { darken }
});

.foo {
  /* make 10% darker */
  color: darken(blue, 0.1);
}

Hey, what happened to glob?

Versions prior to 4.0.0 had a globbing feature built in, but I've since decided to remove this feature from postcss-functions. This means one less dependency and a smaller package size. For people still interested in this feature, you are free to pair postcss-functions with the globbing library of your choice and pass the imported JavaScript files to the functions option as described above.