https://github.com/skyvow/postcss-pxtorem-exclude
Convert pixel units to rem (root em) units using PostCSS
https://github.com/skyvow/postcss-pxtorem-exclude
Last synced: 8 months ago
JSON representation
Convert pixel units to rem (root em) units using PostCSS
- Host: GitHub
- URL: https://github.com/skyvow/postcss-pxtorem-exclude
- Owner: skyvow
- License: mit
- Fork: true (cuth/postcss-pxtorem)
- Created: 2019-11-01T06:53:59.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2019-11-01T07:21:39.000Z (over 6 years ago)
- Last Synced: 2025-01-14T18:58:49.916Z (over 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 56.6 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# postcss-pxtorem-exclude [](http://badge.fury.io/js/postcss-pxtorem-exclude)
A plugin for [PostCSS](https://github.com/ai/postcss) that generates rem units from pixel units.
## Install
```shell
$ npm install postcss-pxtorem-exclude --save-dev
```
## Usage
Pixels are the easiest unit to use (*opinion*). The only issue with them is that they don't let browsers change the default font size of 16. This script converts every px value to a rem from the properties you choose to allow the browser to set the font size.
### Input/Output
*With the default settings, only font related properties are targeted.*
```css
// input
h1 {
margin: 0 0 20px;
font-size: 32px;
line-height: 1.2;
letter-spacing: 1px;
}
// output
h1 {
margin: 0 0 20px;
font-size: 2rem;
line-height: 1.2;
letter-spacing: 0.0625rem;
}
```
### Example
```js
var fs = require('fs');
var postcss = require('postcss');
var pxtorem = require('postcss-pxtorem-exclude');
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
Type: `Object | Null`
Default:
```js
{
exclude: null,
rootValue: 16,
unitPrecision: 5,
propList: ['font', 'font-size', 'line-height', 'letter-spacing'],
selectorBlackList: [],
replace: true,
mediaQuery: false,
minPixelValue: 0
}
```
- `exclude` (RegExp) Files to exclude. Example: `/node_modules|folder_name/i`
- `rootValue` (Number) The root element font size.
- `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.
### Use with gulp-postcss and autoprefixer
```js
var gulp = require('gulp');
var postcss = require('gulp-postcss');
var autoprefixer = require('autoprefixer');
var pxtorem = require('postcss-pxtorem-exclude');
gulp.task('css', function () {
var processors = [
autoprefixer({
browsers: 'last 1 version'
}),
pxtorem({
replace: false
})
];
return gulp.src(['build/css/**/*.css'])
.pipe(postcss(processors))
.pipe(gulp.dest('build/css'));
});
```
### A message about ignoring properties
Currently, the easiest way to have a single property ignored is to use a capital in the pixel unit declaration.
```css
// `px` is converted to `rem`
.convert {
font-size: 16px; // converted to 1rem
}
// `Px` or `PX` is ignored by `postcss-pxtorem-exclude` but still accepted by browsers
.ignore {
border: 1Px solid; // ignored
border-width: 2PX; // ignored
}
```