# postcss-pxtransform

> PostCSS plugin px 转小程序 rpx及h5 rem 单位

Latest version **4.2.1** (published 2026-07-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install postcss-pxtransform
pnpm add postcss-pxtransform
yarn add postcss-pxtransform
bun add postcss-pxtransform
```

## Health

**Score 60/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score; popular repo.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 4.2.1 |
| Published | 2026-07-17 |
| First published | 2018-03-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 18 |
| Dependencies | 0 |
| Unpacked size | 24.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 37673 |
| Author | O2Team |
| Maintainers | defaultlee, yuche |
| Keywords | postcss, css, postcss-plugin, pxtransform |

## Links

- npm: https://www.npmjs.com/package/postcss-pxtransform
- Repository: https://github.com/NervJS/taro
- Homepage: https://github.com/NervJS/taro/tree/main/packages/postcss-pxtransform#readme
- Issues: https://github.com/NervJS/taro/issues
- npm.io page: https://npm.io/package/postcss-pxtransform

## Alternatives

- [style-dictionary](https://npm.io/package/style-dictionary.md) — 2.0M weekly downloads
- [postcss-merge-idents](https://npm.io/package/postcss-merge-idents.md) — 1.7M weekly downloads
- [@fontsource/noto-sans](https://npm.io/package/@fontsource/noto-sans.md) — 93.0K weekly downloads
- [uglifycss](https://npm.io/package/uglifycss.md) — 71.6K weekly downloads
- [mat4-interpolate](https://npm.io/package/mat4-interpolate.md) — 23.3K weekly downloads

## Recent versions

- 4.2.1 (latest) — 2026-07-17
- 4.2.2-beta.5 (beta) — 2026-09-14
- 4.2.2-alpha.2 (alpha) — 2026-09-01
- 3.6.40 (v3-latest) — 2026-04-13
- 3.6.40-beta.1 (v3-beta) — 2026-03-25
- 4.0.9-alpha.8 (test) — 2025-05-14
- 4.0.7-canary.6 (canary) — 2024-11-12
- 4.0.2 (next) — 2024-07-16
- 3.6.15-theta.0 (theta) — 2024-05-06
- 3.6.24-nightly.10 (nightly) — 2024-02-28
- 2.2.22 (2.x) — 2024-01-09
- 3.0.29 (3.0) — 2021-03-09
- 1.3.46 (1.x) — 2020-10-21
- 0.0.0-experimental.2 (experimental) — 2020-04-27
- 4.2.2-beta.4 — 2026-09-08
- … 1133 more at https://npm.io/package/postcss-pxtransform/versions

## README

# PostCSS Pxtransform 

[PostCSS](https://github.com/ai/postcss) 单位转换插件，目前已支持小程序端（px 转rpx），H5 端（px 转 rem）及 RN 端。

基于 [postcss-pxtorem](https://github.com/cuth/postcss-pxtorem/)。

## Install

```shell
$ npm install postcss-pxtransform --save-dev
```

## Usage

### 小程序
```js
options = {
    platform: 'weapp',
    designWidth: 750,
}
```

### H5
```js
options = {
    platform: 'h5',
    designWidth: 750,
}
```

### RN
```js
options = {
    platform: 'rn',
    designWidth: 750,
}
```

### 动态计算designWidth

基础组件库一般是`375`，如果业务系统UI设计是`750`，可以如下配置后`1:1`切图，小程序、H5、RN时有效

```js
options = {
    platform: 'h5',
    designWidth (input) {
      if (input.file.replace(/\\+/g, '/').indexOf('@nutui/nutui-taro') > -1) {
        return 375
      }
      return 750
    },
}
```

### 输入/输出

默认配置下，所有的 px 都会被转换。

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

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

/* h5 output */
h1 {
    margin: 0 0 0.5rem;
    font-size: 1rem;
    line-height: 1.2;
    letter-spacing: 0.025rem;
}

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

```

### example

```js
var fs = require('fs');
var postcss = require('postcss');
var pxtorem = require('postcss-pxtransform');
var css = fs.readFileSync('main.css', 'utf8');
var options = {
    replace: false
};
var processedCss = postcss(pxtorem(options)).process(css).css;

fs.writeFile('main-rem.css', processedCss, function (err) {
  if (err) {
    throw err;
  }
  console.log('Rem file written.');
});
```

## 配置 **options** 
参数默认值如下：

```js
{
    unitPrecision: 5,
    propList: ['*'],
    selectorBlackList: [],
    replace: true,
    mediaQuery: false,
    minPixelValue: 0
}
```

Type: `Object | Null`

###  `platform` （String）（必填）
`weapp` 或 `h5` 或 `rn`

### `designWidth`（Number|Function）（必填）
`640` 或 `750` 或 `828`

### `unitPrecision` (Number) 
The decimal numbers to allow the REM units to grow to.

### `propList` (Array) 
The properties that can change from px to rem.

- Values need to be exact matches.
- Use wildcard `*` to enable all properties. Example: `['*']`
- Use `*` at the start or end of a word. (`['*position*']` will match `background-position-y`)
- Use `!` to not match a property. Example: `['*', '!letter-spacing']`
- Combine the "not" prefix with the other prefixes. Example: `['*', '!font*']`
 
### `selectorBlackList`
(Array) The selectors to ignore and leave as px.
- If value is string, it checks to see if selector contains the string.
  - `['body']` will match `.body-class`
- If value is regexp, it checks to see if the selector matches the regexp.
  - `[/^body$/]` will match `body` but not `.body`

### `replace` (Boolean) 
replaces rules containing rems instead of adding fallbacks.

### `mediaQuery` (Boolean) 
Allow px to be converted in media queries.

### `minPixelValue` (Number) 
Set the minimum pixel value to replace.


## 忽略
### 属性
当前忽略单个属性的最简单的方法，就是 px 单位使用大写字母。

```css
 /*`px` is converted to `rem`*/
.convert {
    font-size: 16px; // converted to 1rem
}

 /* `Px` or `PX` is ignored by `postcss-pxtorem` but still accepted by browsers*/
.ignore {
    border: 1Px solid; // ignored
    border-width: 2PX; // ignored
}
```

### 文件
对于头部包含注释`/*postcss-pxtransform disable*/` 的文件，插件不予处理。

## 剔除
`/*postcss-pxtransform rn eject enable*/` 与 `/*postcss-pxtransform rn eject disable*/` 中间的代码，
在编译成 RN 端的样式的时候，会被删除。建议将 RN 不支持的但 H5 端又必不可少的样式放到这里面。如：样式重制相关的代码。
```css
/*postcss-pxtransform rn eject enable*/

.test {
  color: black;
}

/*postcss-pxtransform rn eject disable*/
```

---
_Source: https://npm.io/package/postcss-pxtransform · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._