postcss-unit-processor

A PostCSS plugin that processes CSS unit values through a user-defined function. Use it to convert units (e.g. px to rem, px to vw), scale values, or apply any custom transformation to CSS numeric values.

Features

• Process any CSS unit (px, rem, vw, em, %, etc.) with a custom function
• Filter by property name with wildcard and negation patterns
• Filter by unit type
• Skip specific selectors via blacklist
• Support for media query processing
• Support for custom/non-standard units (e.g. rpx, dp)
• Exclude files by path string, regex, or function
• Optionally append fallback values instead of replacing

Install

npm install postcss postcss-unit-processor --save-dev

Usage

const postcss = require('postcss');
const unitProcessor = require('postcss-unit-processor');

postcss([
  unitProcessor({
    processor: (value, unit) => {
      if (unit === 'px') {
        return value / 16; // returns a number, unit stays px
      }
    }
  })
]).process(css).css;

The processor function receives the numeric value and unit name, and returns the new value. If nothing is returned (or undefined), the original value is kept unchanged.

processor Function

The core of the plugin. It is called for every matched unit value.

processor(value, unit, node, root)

| Parameter | Type | Description | |-----------|------|-------------| | value | Number | The numeric value | | unit | String | The unit name (e.g. 'px') | | node | Object | The current PostCSS node | | root | Object | The PostCSS root node |

Return value:

• Return a Number — replaces the value, keeps the original unit
• Return an Object { value, unit } — replaces both value and unit; if value cannot be parsed as a number (e.g. undefined, NaN), it is treated as 0
• Return undefined / nothing — keeps the original value unchanged

// Return a number: value changes, unit stays the same
processor: (value, unit) => value / 16
// 32px → 2px  (unit stays px, only the number changes)

// Return an object: both value and unit change
processor: (value, unit) => ({ value: value / 16, unit: 'rem' })
// 32px → 2rem  (both value and unit change)

// Return nothing: no change
processor: (value, unit) => {
  if (unit === 'px') return value / 16;
  // other units: implicitly returns undefined, no change
}

Examples

px to rem

unitProcessor({
  processor: (value, unit) => {
    if (unit === 'px') {
      return {
        value: value / 16,
        unit: 'rem'
      };
    }
  }
})

Input/Output:

/* input */
h1 {
  font-size: 32px;
  margin: 0 0 16px;
  border: 1px solid #ccc;
}

/* output */
h1 {
  font-size: 2rem;
  margin: 0 0 1rem;
  border: 0.0625rem solid #ccc;
}

px to vw (responsive design)

unitProcessor({
  processor: (value, unit) => {
    if (unit === 'px') {
      return {
        value: (value / 375) * 100,
        unit: 'vw'
      };
    }
  }
})

Scale all px values by half

unitProcessor({
  processor: (value, unit) => {
    if (unit === 'px') {
      return value / 2;
    }
  }
})

Input/Output:

/* input */
h1 {
  margin: 0 0 20px;
  font-size: 32px;
  line-height: 1.2;
  letter-spacing: 1px;
}

/* output */
h1 {
  margin: 0 0 10px;
  font-size: 16px;
  line-height: 1.2;
  letter-spacing: 0.5px;
}

Append fallback instead of replacing

unitProcessor({
  replace: false,
  processor: (value, unit) => {
    if (unit === 'px') {
      return {
        value: value / 16,
        unit: 'rem'
      };
    }
  }
})

/* input */
.box {
  font-size: 16px;
}

/* output */
.box {
  font-size: 16px;
  font-size: 1rem;
}

Options

{
  processor: (value) => value,  // default: identity function
  unitPrecision: 5,
  propList: ['*'],
  unitList: ['*'],
  selectorBlackList: [],
  replace: true,
  mediaQuery: false,
  exclude: /node_modules/i,
  customUnitList: []
}

processor

Type: Function

The unit processing function. See processor Function above.

unitPrecision

Type: Number Default: 5

Decimal places to round the processed value to.

unitList

Type: Array Default: ['*']

Which units to pass to the processor function.

// All units (default)
unitList: ['*']

// Only px
unitList: ['px']

// px and rem
unitList: ['px', 'rem']

// All units except rem
unitList: ['*', '!rem']

propList

Type: Array Default: ['*']

Which CSS properties to process.

// All properties (default)
propList: ['*']

// Only font-size
propList: ['font-size']

// All properties except letter-spacing
propList: ['*', '!letter-spacing']

// Properties containing "size"
propList: ['*size*']

// Properties starting with "font"
propList: ['font*']

// Properties ending with "width"
propList: ['*width']

selectorBlackList

Type: Array Default: []

Selectors to skip. Accepts strings (substring match) or regular expressions.

selectorBlackList: ['.ignore', /^\.no-convert/]

/* .ignore matches the blacklist, skipped */
.ignore { font-size: 16px; }       /* → 16px (unchanged) */

/* normal selector, processed */
.convert { font-size: 16px; }      /* → processed by your processor function */

replace

Type: Boolean Default: true

• true — replace the original value
• false — insert the processed value as a new declaration after the original (useful for fallbacks)

mediaQuery

Type: Boolean Default: false

Whether to process values inside @media queries.

// Enable media query processing
mediaQuery: true

/* input */
@media (max-width: 768px) { ... }

/* output (with px→rem processor) */
@media (max-width: 48rem) { ... }

exclude

Type: String | RegExp | Function Default: /node_modules/i

File paths to exclude from processing.

// String: skip files whose path contains this string
exclude: 'src/legacy'

// RegExp
exclude: /\/legacy\//i

// Function
exclude: (filePath) => filePath.includes('legacy')

customUnitList

Type: Array Default: []

Additional non-standard units to recognize and process (e.g. rpx used in WeChat Mini Programs, dp used in Android).

customUnitList: ['rpx', 'dp']

Only strings consisting entirely of letters (a-z, A-Z) or the % character are accepted. Invalid entries are silently ignored.

Default recognized units: px, pt, pc, cm, mm, in, %, em, rem, ch, vh, vw, vmin, vmax, ex

Framework Integration

Vite / Vue / React

// vite.config.js
import unitProcessor from 'postcss-unit-processor';

export default {
  css: {
    postcss: {
      plugins: [
        unitProcessor({
          processor: (value, unit) => {
            if (unit === 'px') {
              return {
                value: value / 16,
                unit: 'rem'
              };
            }
          }
        })
      ]
    }
  }
};

webpack (postcss-loader)

// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-unit-processor')({
      processor: (value, unit) => {
        if (unit === 'px') {
          return {
            value: value / 16,
            unit: 'rem'
          };
        }
      }
    })
  ]
};

gulp

const gulp = require('gulp');
const postcss = require('gulp-postcss');
const unitProcessor = require('postcss-unit-processor');

gulp.task('css', () => {
  return gulp.src('src/**/*.css')
    .pipe(postcss([
      unitProcessor({
        processor: (value, unit) => {
          if (unit === 'px') {
            return value / 2;
          }
        }
      })
    ]))
    .pipe(gulp.dest('dist'));
});

License

MIT