{"id":19462517,"url":"https://github.com/hex-ci/postcss-unit-processor","last_synced_at":"2026-03-15T10:55:34.864Z","repository":{"id":57328616,"uuid":"380961589","full_name":"hex-ci/postcss-unit-processor","owner":"hex-ci","description":"PostCSS plugin to process css unit.","archived":false,"fork":false,"pushed_at":"2021-07-02T05:37:20.000Z","size":13,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-21T11:03:22.039Z","etag":null,"topics":["postcss","postcss-plugin"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hex-ci.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-06-28T08:33:06.000Z","updated_at":"2022-08-08T10:10:17.000Z","dependencies_parsed_at":"2022-09-04T10:20:38.444Z","dependency_job_id":null,"html_url":"https://github.com/hex-ci/postcss-unit-processor","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hex-ci%2Fpostcss-unit-processor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hex-ci%2Fpostcss-unit-processor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hex-ci%2Fpostcss-unit-processor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hex-ci%2Fpostcss-unit-processor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hex-ci","download_url":"https://codeload.github.com/hex-ci/postcss-unit-processor/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250782033,"owners_count":21486376,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["postcss","postcss-plugin"],"created_at":"2024-11-10T18:02:09.771Z","updated_at":"2026-03-15T10:55:34.859Z","avatar_url":"https://github.com/hex-ci.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# postcss-unit-processor\n\n[![npm version](https://badgen.net/npm/v/postcss-unit-processor)](https://www.npmjs.com/package/postcss-unit-processor) [![codecov](https://codecov.io/github/hex-ci/postcss-unit-processor/graph/badge.svg?token=YKJBZI9LGK)](https://codecov.io/github/hex-ci/postcss-unit-processor) [![Downloads](https://badgen.net/npm/dt/postcss-unit-processor)](https://www.npmjs.com/package/postcss-unit-processor)\n\nA 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.\n\n## Features\n\n- Process any CSS unit (`px`, `rem`, `vw`, `em`, `%`, etc.) with a custom function\n- Filter by property name with wildcard and negation patterns\n- Filter by unit type\n- Skip specific selectors via blacklist\n- Support for media query processing\n- Support for custom/non-standard units (e.g. `rpx`, `dp`)\n- Exclude files by path string, regex, or function\n- Optionally append fallback values instead of replacing\n\n## Install\n\n```shell\nnpm install postcss postcss-unit-processor --save-dev\n```\n\n## Usage\n\n```js\nconst postcss = require('postcss');\nconst unitProcessor = require('postcss-unit-processor');\n\npostcss([\n  unitProcessor({\n    processor: (value, unit) =\u003e {\n      if (unit === 'px') {\n        return value / 16; // returns a number, unit stays px\n      }\n    }\n  })\n]).process(css).css;\n```\n\nThe `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.\n\n## processor Function\n\nThe core of the plugin. It is called for every matched unit value.\n\n```js\nprocessor(value, unit, node, root)\n```\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `value` | `Number` | The numeric value |\n| `unit` | `String` | The unit name (e.g. `'px'`) |\n| `node` | `Object` | The current PostCSS node |\n| `root` | `Object` | The PostCSS root node |\n\n**Return value:**\n\n- Return a `Number` — replaces the value, keeps the original unit\n- 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`\n- Return `undefined` / nothing — keeps the original value unchanged\n\n```js\n// Return a number: value changes, unit stays the same\nprocessor: (value, unit) =\u003e value / 16\n// 32px → 2px  (unit stays px, only the number changes)\n\n// Return an object: both value and unit change\nprocessor: (value, unit) =\u003e ({ value: value / 16, unit: 'rem' })\n// 32px → 2rem  (both value and unit change)\n\n// Return nothing: no change\nprocessor: (value, unit) =\u003e {\n  if (unit === 'px') return value / 16;\n  // other units: implicitly returns undefined, no change\n}\n```\n\n## Examples\n\n### px to rem\n\n```js\nunitProcessor({\n  processor: (value, unit) =\u003e {\n    if (unit === 'px') {\n      return {\n        value: value / 16,\n        unit: 'rem'\n      };\n    }\n  }\n})\n```\n\nInput/Output:\n\n```css\n/* input */\nh1 {\n  font-size: 32px;\n  margin: 0 0 16px;\n  border: 1px solid #ccc;\n}\n\n/* output */\nh1 {\n  font-size: 2rem;\n  margin: 0 0 1rem;\n  border: 0.0625rem solid #ccc;\n}\n```\n\n### px to vw (responsive design)\n\n```js\nunitProcessor({\n  processor: (value, unit) =\u003e {\n    if (unit === 'px') {\n      return {\n        value: (value / 375) * 100,\n        unit: 'vw'\n      };\n    }\n  }\n})\n```\n\n### Scale all px values by half\n\n```js\nunitProcessor({\n  processor: (value, unit) =\u003e {\n    if (unit === 'px') {\n      return value / 2;\n    }\n  }\n})\n```\n\nInput/Output:\n\n```css\n/* input */\nh1 {\n  margin: 0 0 20px;\n  font-size: 32px;\n  line-height: 1.2;\n  letter-spacing: 1px;\n}\n\n/* output */\nh1 {\n  margin: 0 0 10px;\n  font-size: 16px;\n  line-height: 1.2;\n  letter-spacing: 0.5px;\n}\n```\n\n### Append fallback instead of replacing\n\n```js\nunitProcessor({\n  replace: false,\n  processor: (value, unit) =\u003e {\n    if (unit === 'px') {\n      return {\n        value: value / 16,\n        unit: 'rem'\n      };\n    }\n  }\n})\n```\n\n```css\n/* input */\n.box {\n  font-size: 16px;\n}\n\n/* output */\n.box {\n  font-size: 16px;\n  font-size: 1rem;\n}\n```\n\n## Options\n\n```js\n{\n  processor: (value) =\u003e value,  // default: identity function\n  unitPrecision: 5,\n  propList: ['*'],\n  unitList: ['*'],\n  selectorBlackList: [],\n  replace: true,\n  mediaQuery: false,\n  exclude: /node_modules/i,\n  customUnitList: []\n}\n```\n\n### `processor`\n\nType: `Function`\n\nThe unit processing function. See [processor Function](#processor-function) above.\n\n### `unitPrecision`\n\nType: `Number`\nDefault: `5`\n\nDecimal places to round the processed value to.\n\n### `unitList`\n\nType: `Array`\nDefault: `['*']`\n\nWhich units to pass to the processor function.\n\n```js\n// All units (default)\nunitList: ['*']\n\n// Only px\nunitList: ['px']\n\n// px and rem\nunitList: ['px', 'rem']\n\n// All units except rem\nunitList: ['*', '!rem']\n```\n\n### `propList`\n\nType: `Array`\nDefault: `['*']`\n\nWhich CSS properties to process.\n\n```js\n// All properties (default)\npropList: ['*']\n\n// Only font-size\npropList: ['font-size']\n\n// All properties except letter-spacing\npropList: ['*', '!letter-spacing']\n\n// Properties containing \"size\"\npropList: ['*size*']\n\n// Properties starting with \"font\"\npropList: ['font*']\n\n// Properties ending with \"width\"\npropList: ['*width']\n```\n\n### `selectorBlackList`\n\nType: `Array`\nDefault: `[]`\n\nSelectors to skip. Accepts strings (substring match) or regular expressions.\n\n```js\nselectorBlackList: ['.ignore', /^\\.no-convert/]\n```\n\n```css\n/* .ignore matches the blacklist, skipped */\n.ignore { font-size: 16px; }       /* → 16px (unchanged) */\n\n/* normal selector, processed */\n.convert { font-size: 16px; }      /* → processed by your processor function */\n```\n\n### `replace`\n\nType: `Boolean`\nDefault: `true`\n\n- `true` — replace the original value\n- `false` — insert the processed value as a new declaration after the original (useful for fallbacks)\n\n### `mediaQuery`\n\nType: `Boolean`\nDefault: `false`\n\nWhether to process values inside `@media` queries.\n\n```js\n// Enable media query processing\nmediaQuery: true\n```\n\n```css\n/* input */\n@media (max-width: 768px) { ... }\n\n/* output (with px→rem processor) */\n@media (max-width: 48rem) { ... }\n```\n\n### `exclude`\n\nType: `String | RegExp | Function`\nDefault: `/node_modules/i`\n\nFile paths to exclude from processing.\n\n```js\n// String: skip files whose path contains this string\nexclude: 'src/legacy'\n\n// RegExp\nexclude: /\\/legacy\\//i\n\n// Function\nexclude: (filePath) =\u003e filePath.includes('legacy')\n```\n\n### `customUnitList`\n\nType: `Array`\nDefault: `[]`\n\nAdditional non-standard units to recognize and process (e.g. `rpx` used in WeChat Mini Programs, `dp` used in Android).\n\n```js\ncustomUnitList: ['rpx', 'dp']\n```\n\nOnly strings consisting entirely of letters (`a-z`, `A-Z`) or the `%` character are accepted. Invalid entries are silently ignored.\n\n**Default recognized units:** `px`, `pt`, `pc`, `cm`, `mm`, `in`, `%`, `em`, `rem`, `ch`, `vh`, `vw`, `vmin`, `vmax`, `ex`\n\n## Framework Integration\n\n### Vite / Vue / React\n\n```js\n// vite.config.js\nimport unitProcessor from 'postcss-unit-processor';\n\nexport default {\n  css: {\n    postcss: {\n      plugins: [\n        unitProcessor({\n          processor: (value, unit) =\u003e {\n            if (unit === 'px') {\n              return {\n                value: value / 16,\n                unit: 'rem'\n              };\n            }\n          }\n        })\n      ]\n    }\n  }\n};\n```\n\n### webpack (postcss-loader)\n\n```js\n// postcss.config.js\nmodule.exports = {\n  plugins: [\n    require('postcss-unit-processor')({\n      processor: (value, unit) =\u003e {\n        if (unit === 'px') {\n          return {\n            value: value / 16,\n            unit: 'rem'\n          };\n        }\n      }\n    })\n  ]\n};\n```\n\n### gulp\n\n```js\nconst gulp = require('gulp');\nconst postcss = require('gulp-postcss');\nconst unitProcessor = require('postcss-unit-processor');\n\ngulp.task('css', () =\u003e {\n  return gulp.src('src/**/*.css')\n    .pipe(postcss([\n      unitProcessor({\n        processor: (value, unit) =\u003e {\n          if (unit === 'px') {\n            return value / 2;\n          }\n        }\n      })\n    ]))\n    .pipe(gulp.dest('dist'));\n});\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhex-ci%2Fpostcss-unit-processor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhex-ci%2Fpostcss-unit-processor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhex-ci%2Fpostcss-unit-processor/lists"}