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 W3C calc() 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, the deprecated unwrapSingleNegativeNumber alias, 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: 200px) {
  div {
    width: 100px;
  }
}

selectors (default: false)

Reduces calc() functions found in selectors. Selectors do not accept calc() functions, so the plugin replaces them with their reduced values. Finite negative and fractional unitless results are serialized as bare values because a selector cannot contain a calc() function; the plugin enables the unwrapSingleValue automatically for selectors.

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 when a calc() body fails to parse or simplify. Matches @csstools/css-calc's shape:

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. Commutative operands serialize numeric-first, matching @csstools/css-calc: 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 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
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

Performance changes to the parser, analyzer, simplifier, or serializer should be checked with the benchmarks. pnpm benchmark:arithmetic-chains and pnpm benchmark:nested-fallbacks compare the working tree against HEAD using 20 fresh-process paired blocks by default and write git-ignored schema-v2 reports under reports/benchmarks/. Re-check a saved report with pnpm benchmark:reanalyze <report>. pnpm benchmark:corpus compares the whole pipeline with @csstools/css-calc on real-world expressions and is report-only.

These benchmarks time only the parser (or, for the corpus, the whole reducer) on one machine, and a pass means "no regression detected at the declared margin", not "no change". Read BENCHMARKS.md before interpreting results.

The PostCSS benchmark awaits postcss().process(...), and that await already triggers result stringification. It therefore does not add a redundant result.css access.

Changelog

License