README.md 4.17 KB

PostCSS Stepped Value Functions PostCSS Logo

npm version CSS Standard Status Build Status Discord

PostCSS Stepped Value Functions lets you use round, rem and mod stepped value functions, following the CSS Values 4.

.test-functions {
    padding: 8px mod(18px, 5px) 1px calc(rem(15px, 6px) + 50%);
    transform: rotate(mod(-140deg, -90deg));
    top: round(15px, 4px);
    right: round(nearest, 15px, 4px);
    bottom: round(up, 15px, 7px);
    left: round(down, 15px, 4px);
    width: round(to-zero, 15px, 4px);
}

/* becomes */

.test-functions {
    padding: 8px 3px 1px calc(3px + 50%);
    transform: rotate(-50deg);
    top: 16px;
    right: 16px;
    bottom: 21px;
    left: 12px;
    width: 12px;
}

Usage

Add PostCSS Stepped Value Functions to your project:

npm install postcss @csstools/postcss-stepped-value-functions --save-dev

Use it as a PostCSS plugin:

const postcss = require('postcss');
const postcssSteppedValueFunctions = require('@csstools/postcss-stepped-value-functions');

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

PostCSS Stepped Value Functions runs in all Node environments, with special instructions for:

Node PostCSS CLI Webpack Create React App Gulp Grunt

⚠️ About custom properties

Given the dynamic nature of custom properties it's impossible to know what the variable value is, which means the plugin can't compute a final value for the stylesheet.

Because of that, any usage that contains a var is skipped.

Options

preserve

The preserve option determines whether the original notation is preserved. By default, it is not preserved.

postcssSteppedValueFunctions({ preserve: true })
.test-functions {
    padding: 8px mod(18px, 5px) 1px calc(rem(15px, 6px) + 50%);
    transform: rotate(mod(-140deg, -90deg));
    top: round(15px, 4px);
    right: round(nearest, 15px, 4px);
    bottom: round(up, 15px, 7px);
    left: round(down, 15px, 4px);
    width: round(to-zero, 15px, 4px);
}

/* becomes */

.test-functions {
    padding: 8px 3px 1px calc(3px + 50%);
    padding: 8px mod(18px, 5px) 1px calc(rem(15px, 6px) + 50%);
    transform: rotate(-50deg);
    transform: rotate(mod(-140deg, -90deg));
    top: 16px;
    top: round(15px, 4px);
    right: 16px;
    right: round(nearest, 15px, 4px);
    bottom: 21px;
    bottom: round(up, 15px, 7px);
    left: 12px;
    left: round(down, 15px, 4px);
    width: 12px;
    width: round(to-zero, 15px, 4px);
}

onInvalid

onInvalid option allows you to assign the warn value so you can get warnings when the usage of the functions is wrong.

postcssSteppedValueFunctions({ onInvalid: 'warn' })
.invalid {
    font-size: mod(18px, 5rem);
}

Will produce on the terminal:

[postcss-stepped-value-functions]: Failed to transform mod(18px, 5rem) as the units don't match