PostCSS Calc

PostCSS Calc lets you reduce calc() references whenever it's possible. When an expression mixes units that cannot be combined exactly (such as px and em), or contains values only known at runtime (such as var()), the unresolved part is left for the browser's CSS Values 4 implementation.

Installation

npm install postcss-calc

PostCSS usage

// dependencies
var fs = require('fs');
var postcss = require('postcss');
var calc = require('postcss-calc');

// css to be processed
var css = fs.readFileSync('input.css', 'utf8');

// process css
var output = postcss().use(calc()).process(css).css;

Using this input.css:

h1 {
  font-size: calc(16px * 2);
  height: calc(100px - 2em);
  width: calc(2 * var(--base-width));
  margin-bottom: calc(16px * 1.5);
}

you will get:

h1 {
  font-size: calc(32px);
  height: calc(100px - 2em);
  width: calc(2 * var(--base-width));
  margin-bottom: calc(24px);
}

Checkout tests for more examples.

Use the reducer without PostCSS

For a single CSS component-value string, import the dedicated reducer entry point. It reduces calc() and the supported CSS math functions it finds while leaving all other text untouched.

import reduceCalc from 'postcss-calc/reduce';

reduceCalc('calc(1in + 10px)');
// => 'calc(106px)'

reduceCalc('min(50px, calc(2 * 40px))');
// => 'calc(50px)'

It accepts precision, unwrapSingleValue, warnWhenCannotResolve, onParseError, and onWarn:

const result = reduceCalc('calc(100% + var(--gap))', {
  precision: false,
  warnWhenCannotResolve: true,
  onWarn: console.warn,
  onParseError(error, input) {
    console.error(`Invalid calculation: ${input}`, error);
  },
});

Unlike the PostCSS plugin, the standalone reducer does not show warnings by default; provide onParseError and/or onWarn if you want diagnostics.

Standalone reducer options

unwrapSingleValue (default: false)

Serializes a fully resolved finite scalar result without calculation syntax. Keep the default for standard CSS so the browser can perform range clamping and integer rounding. Set it to true for a non-standard context that requires a bare value, such as a selector:

reduceCalc('calc(5px - 10px)');
// => 'calc(-5px)'

reduceCalc('calc(5px - 10px)', { unwrapSingleValue: true });
// => '-5px'

reduceCalc('calc(1 / 2)', { unwrapSingleValue: true });
// => '.5'

The published unwrapSingleNegativeNumber option is retained as a deprecated alias for unwrapSingleValue.

PostCSS plugin options

These options apply when using the PostCSS plugin:

postcss().use(calc({ precision: 10 }));

precision (default: 5)

Allows you to define the precision for decimal numbers. Set it to false to disable rounding and preserve full IEEE-754 floating-point precision (emitting the shortest round-tripping decimal representation).

Values below 1 keep precision significant digits (.0123456px becomes .012346px), and larger values keep precision decimals. Divisions and unit conversions are folded only when the result is exact at the precision; otherwise they stay symbolic and everything around them is still simplified:

.a {
  width: calc(100% / 4);
} /* calc(25%) */
.b {
  width: calc(100% / 3);
} /* calc(100% / 3), not 33.33333% */
.c {
  width: calc(1cm + 1px);
} /* calc(1cm + 1px) */
.d {
  width: calc(1px + 1pt);
} /* calc(1.75pt) */

With precision: false nothing is rounded, so every division is folded.

var out = postcss()
  .use(calc({ precision: 10 }))
  .process(css).css;

unwrapSingleValue (default: false)

Serializes fully resolved finite scalar results without calculation syntax. This can discard browser-applied range clamping or integer rounding. Selectors enable it automatically because selectors cannot contain calc().

warnWhenCannotResolve (default: false)

Adds warnings when calc() are not reduced to a single value.

var out = postcss()
  .use(calc({ warnWhenCannotResolve: true }))
  .process(css).css;

mediaQueries (default: false)

Allows calc() usage in media query parameters.

var out = postcss()
  .use(calc({ mediaQueries: true }))
  .process(css).css;

Example:

@media (min-width: calc(100px + 100px)) {
  div {
    width: 100px;
  }
}

With mediaQueries: true, this becomes:

@media (min-width: calc(200px)) {
  div {
    width: 100px;
  }
}

Add unwrapSingleValue: true to get the bare value, (min-width: 200px).

selectors (default: false)

Reduces calc() functions found in selectors. Selectors do not accept calc() functions, so the plugin replaces them with their reduced values, as if unwrapSingleValue were enabled.

var out = postcss()
  .use(calc({ selectors: true }))
  .process(css).css;

Example:

div:nth-child(calc(1 + 2)) {
  width: 100px;
}

With selectors: true, this becomes div:nth-child(3).

onParseError

Callback invoked with the error and the input value when a calc() body fails to parse or simplify:

postcss().use(
  calc({
    onParseError: (err, input) => {
      throw err; // or log, route to a different channel, etc.
    },
  })
);

When omitted, errors are reported via PostCSS result.warn() so the plugin never throws at the postcss level.

Behavior differences from the legacy parser

The legacy jison-generated parser was replaced by a hand-written Pratt parser whose simplifier follows CSS Values 4. Most inputs reduce to identical output; the differences are spec-aligned or canonical-form decisions:

• Strict whitespace (§10.1). calc(2px+3px) is invalid CSS (binary + / - require surrounding whitespace) and is preserved with a warning instead of reduced.
• Canonical operand order. Sums serialize numbers first, then dimensions in first-seen order, then unresolved terms: calc(var(--foo) + 10px) → calc(10px + var(--foo)).
• Zero buckets are kept. calc(100px - (100px - 100%)) → calc(0px + 100%), not 100% — WPT calc-serialization-002 requires the zero term because it carries the length-percentage type.
• Constant folding. calc(43 + pi) now folds to calc(46.14159) (§10.7.1). Previously pi / e stayed symbolic.
• Distributive multiplication. calc(0.5 * (100vw - 10px)) becomes calc(50vw - 5px).
• Unit case normalization. 2PX becomes 2px (CSS units are case- insensitive; lowercase is conventional).
• Spec-style spaced operators. 2px*var(--x) is serialized as 2px * var(--x). The tokenizer is unaffected; only output spacing differs.
• Division by zero / by a unit. calc(500px/0) reduces to calc(infinity * 1px) (§10.13) instead of throwing. Use onParseError if you want validation behavior.

---

Related PostCSS plugins

To replace the value of CSS custom properties at build time, try PostCSS Custom Properties.

Contributing

Work on a branch, install dev-dependencies, respect coding style & run tests before submitting a bug fix or a feature. See CONTRIBUTING.md for the full guidelines. The project uses pnpm.

git clone git@github.com:postcss/postcss-calc.git
cd postcss-calc
git checkout -b patch-1
pnpm install
pnpm test
pnpm lint

The normal test run uses a deterministic structural sample of the harvested real-world corpus. Run the complete differential corpus before releases or when changing parsing/simplification behavior:

pnpm test:corpus:full

Check performance changes with the benchmarks described in BENCHMARKS.md, and read it before interpreting results.

Changelog

License