or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-postcss-pxtorem

A PostCSS plugin that converts px units to rem units for responsive design.

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/postcss-pxtorem@6.1.x

To install, run

npx @tessl/cli install tessl/npm-postcss-pxtorem@6.1.0

PostCSS PxToRem

PostCSS PxToRem is a PostCSS plugin that converts pixel (px) units to rem units in CSS stylesheets. It enables responsive design by allowing browsers to scale based on user font size preferences, while providing comprehensive configuration options for selective conversion.

Package Information

Package Name: postcss-pxtorem
Package Type: npm
Language: JavaScript
Installation: npm install postcss postcss-pxtorem --save-dev

Core Imports

const pxtorem = require('postcss-pxtorem');

For ES modules:

import pxtorem from 'postcss-pxtorem';

Basic Usage

const postcss = require('postcss');
const pxtorem = require('postcss-pxtorem');

// Basic usage with default options
const result = postcss()
  .use(pxtorem())
  .process(css)
  .css;

// With custom options
const result = postcss()
  .use(pxtorem({
    rootValue: 16,
    propList: ['*'],
    replace: true
  }))
  .process(css)
  .css;

Architecture

PostCSS PxToRem follows the standard PostCSS plugin architecture with three main processing hooks:

Once Hook: Initializes plugin for each CSS file, determining file exclusion status and creating the pixel replacement function based on configuration
Declaration Hook: Processes each CSS property declaration, applying px-to-rem conversion based on property matching rules and selector blacklists
AtRule Hook: Handles CSS at-rules like @media queries when mediaQuery option is enabled

Internal Utilities

The plugin uses several internal utility modules from the lib/ directory:

pixel-unit-regex.js: Creates regex patterns for matching pixel units while excluding values in quotes, url(), and var() functions
filter-prop-list.js: Provides property list filtering with support for wildcards, exact matches, and exclusion patterns (using ! prefix)
type.js: Type checking utilities for validating configuration options (isString, isFunction, etc.)

Processing Pipeline

Initialization: Plugin validates options, converts legacy option names, and prepares matching functions
File Processing: Each CSS file is checked against exclusion rules to determine if processing should occur
Declaration Processing: Property declarations are filtered by propList patterns and selector blacklists before conversion
Value Replacement: Pixel values are converted to rem units using the specified root value and precision settings

Capabilities

Plugin Factory Function

Creates a PostCSS plugin instance with the specified configuration options.

/**
 * Creates a PostCSS plugin for converting px to rem units
 * @param {Object} options - Configuration options for the plugin
 * @returns {Object} PostCSS plugin object
 */
function pxtorem(options = {});

Configuration Options

The plugin accepts a comprehensive set of configuration options to control conversion behavior.

interface PxToRemOptions {
  /** Root element font size or function returning root size */
  rootValue?: number | ((input: PostCSSInput) => number);
  /** Decimal precision for rem units */
  unitPrecision?: number;
  /** Properties to convert from px to rem */
  propList?: string[];
  /** Selectors to ignore during conversion */
  selectorBlackList?: (string | RegExp)[];
  /** Replace px values instead of adding fallbacks */
  replace?: boolean;
  /** Convert px in media queries */
  mediaQuery?: boolean;
  /** Minimum pixel value to convert */
  minPixelValue?: number;
  /** File exclusion pattern */
  exclude?: string | RegExp | ((filePath: string) => boolean);
  /** Unit to convert from (default: "px") */
  unit?: string;
}

Default Options

The plugin uses the following default configuration:

const defaultOptions = {
  rootValue: 16,
  unitPrecision: 5,
  selectorBlackList: [],
  propList: ['font', 'font-size', 'line-height', 'letter-spacing', 'word-spacing'],
  replace: true,
  mediaQuery: false,
  minPixelValue: 0,
  exclude: null,
  unit: 'px'
};

Property List Patterns

The propList option supports various matching patterns for selective property conversion:

// Property list pattern examples
const propListPatterns = {
  /** Exact property names */
  exact: ['font-size', 'margin', 'padding'],
  /** All properties */
  all: ['*'],
  /** Properties containing substring */
  contains: ['*position*'], // matches background-position-x, etc.
  /** Properties starting with prefix */
  startsWith: ['font*'], // matches font-size, font-weight, etc.
  /** Properties ending with suffix */
  endsWith: ['*-spacing'], // matches letter-spacing, word-spacing, etc.
  /** Negated patterns (exclude from conversion) */
  exclude: ['*', '!border*'], // all properties except those starting with 'border'
};

Usage Examples

Basic Font Size Conversion

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

/* Output CSS (with default options) */
h1 {
  margin: 0 0 20px;
  font-size: 2rem;
  line-height: 1.2;
  letter-spacing: 0.0625rem;
}

Convert All Properties

const postcss = require('postcss');
const pxtorem = require('postcss-pxtorem');

const result = postcss()
  .use(pxtorem({
    propList: ['*'], // Convert all properties
    replace: false   // Keep px as fallback
  }))
  .process(css)
  .css;

/* Input */
.element {
  width: 320px;
  margin: 10px 20px;
  border: 1px solid #ccc;
}

/* Output */
.element {
  width: 320px;
  width: 20rem;
  margin: 10px 20px;
  margin: 0.625rem 1.25rem;
  border: 1px solid #ccc;
  border: 0.0625rem solid #ccc;
}

Selective Conversion with Exclusions

const options = {
  propList: ['*', '!border*', '!outline*'],
  selectorBlackList: ['.ignore', /^\.mobile-/],
  minPixelValue: 2
};

const result = postcss()
  .use(pxtorem(options))
  .process(css)
  .css;

Dynamic Root Value

const options = {
  rootValue: (input) => {
    // Different root values based on file path
    if (input.file.includes('mobile')) {
      return 14;
    }
    return 16;
  }
};

File Exclusion

const options = {
  exclude: /node_modules/i, // Exclude node_modules files
  // or function-based exclusion
  exclude: (file) => file.includes('vendor')
};

Media Query Conversion

const options = {
  mediaQuery: true // Enable px to rem conversion in media queries
};

const result = postcss()
  .use(pxtorem(options))
  .process(css)
  .css;

/* Input */
@media (min-width: 768px) {
  .container {
    max-width: 1200px;
  }
}

/* Output */
@media (min-width: 48rem) {
  .container {
    max-width: 75rem;
  }
}

Types

PostCSS Plugin Object

interface PostCSSPlugin {
  /** Plugin identifier */
  postcssPlugin: 'postcss-pxtorem';
  /** Initialize plugin for each CSS file */
  Once(css: PostCSSRoot): void;
  /** Process each CSS declaration */
  Declaration(decl: PostCSSDeclaration): void;
  /** Process CSS at-rules (like @media) */
  AtRule(atRule: PostCSSAtRule): void;
}

PostCSS Input

interface PostCSSInput {
  /** File path of the CSS being processed */
  file: string;
  /** CSS source content */
  css: string;
}

Advanced Configuration

Case-Sensitive Unit Conversion

By default, only lowercase 'px' units are converted. Uppercase variants ('Px', 'PX') are ignored:

/* This allows selective ignoring within the same file */
.convert {
  font-size: 16px; /* converted to 1rem */
}

.ignore {
  border: 1Px solid; /* ignored - keeps Px */
  border-width: 2PX; /* ignored - keeps PX */
}

Integration with Build Tools

// Gulp integration
const gulp = require('gulp');
const postcss = require('gulp-postcss');
const pxtorem = require('postcss-pxtorem');

gulp.task('css', () => {
  return gulp.src('src/**/*.css')
    .pipe(postcss([
      pxtorem({
        replace: false
      })
    ]))
    .pipe(gulp.dest('dist'));
});

// Webpack integration (postcss.config.js)
module.exports = {
  plugins: [
    require('postcss-pxtorem')({
      rootValue: 16,
      propList: ['*']
    })
  ]
};

Plugin Compatibility

This plugin follows PostCSS plugin conventions and includes the required compatibility flag:

// Plugin compatibility marker
pxtorem.postcss = true;