or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-postcss-convert-values

PostCSS plugin that optimizes CSS by converting values to use more efficient units

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/postcss-convert-values@7.0.x

To install, run

npx @tessl/cli install tessl/npm-postcss-convert-values@7.0.0

index.mddocs/

PostCSS Convert Values

PostCSS Convert Values is a PostCSS plugin that optimizes CSS by converting values to use more efficient units where possible. It reduces CSS file size by converting time values (e.g., 500ms to .5s), length values (e.g., 16px to 1pc), angle values (e.g., degrees to turns), and removing unnecessary units from zero values.

Package Information

  • Package Name: postcss-convert-values
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install postcss-convert-values

Core Imports

const convertValues = require("postcss-convert-values");

For ES modules:

import convertValues from "postcss-convert-values";

Basic Usage

const postcss = require("postcss");
const convertValues = require("postcss-convert-values");

// Basic usage with default options
const result = await postcss([convertValues()])
  .process("h1 { font-size: 16px; transition: opacity 500ms; }", {
    from: "input.css",
    to: "output.css"
  });
// Result: "h1 { font-size: 1pc; transition: opacity .5s; }"

// With custom options
const customResult = await postcss([
  convertValues({
    length: true,
    time: true,
    angle: false,
    precision: 2
  })
]).process(css, { from: undefined });

Capabilities

Plugin Creator Function

Creates a PostCSS plugin instance with optional configuration.

/**
 * Creates a PostCSS plugin that converts CSS values to more efficient units
 * @param {Options} opts - Plugin configuration options
 * @returns {Plugin} PostCSS plugin instance
 */
function convertValues(opts?: Options): Plugin;

interface Options {
  /** Enable/disable length unit conversions (px ↔ pc/pt/in). Default: true */
  length?: boolean;
  /** Enable/disable time unit conversions (ms ↔ s). Default: true */
  time?: boolean;
  /** Enable/disable angle unit conversions (deg ↔ turn). Default: true */
  angle?: boolean;
  /** Control decimal precision for px values. Default: false */
  precision?: false | number;
  /** Override browserslist configuration */
  overrideBrowserslist?: string | string[];
  /** Browserslist stats option */
  stats?: any;
  /** Browserslist path option */
  path?: string;
  /** Browserslist environment option */
  env?: string;
}

Usage Examples:

const postcss = require("postcss");
const convertValues = require("postcss-convert-values");

// Enable all conversions (default)
postcss([convertValues()]);

// Disable specific conversions
postcss([convertValues({
  length: false,  // Keep px units as-is
  time: true,     // Convert ms ↔ s
  angle: false    // Keep deg units as-is
})]);

// Set precision for pixel values
postcss([convertValues({
  precision: 2  // Round to 2 decimal places
})]);

// Override browserslist for IE11 compatibility
postcss([convertValues({
  overrideBrowserslist: ["ie 11"]
})]);

Plugin PostCSS Marker

Indicates this is a PostCSS plugin.

/** PostCSS plugin marker property */
convertValues.postcss: true;

Conversion Behaviors

Length Unit Conversions

When length: true (default), the plugin converts between absolute length units to find the shortest representation:

  • px (pixels) ↔ pc (picas): 16px = 1pc
  • px (pixels) ↔ pt (points): 3px = 4pt (1.33px = 1pt)
  • px (pixels) ↔ in (inches): 96px = 1in
/* Input */
h1 { font-size: 16px; width: 192px; height: 120px; }

/* Output */
h1 { font-size: 1pc; width: 2in; height: 90pt; }

Time Unit Conversions

When time: true (default), the plugin converts between time units:

  • ms (milliseconds) ↔ s (seconds): 1000ms = 1s
/* Input */
.fade { transition: opacity 500ms, transform 1500ms; }

/* Output */
.fade { transition: opacity .5s, transform 1.5s; }

Angle Unit Conversions

When angle: true (default), the plugin converts between angle units:

  • deg (degrees) ↔ turn (turns): 360deg = 1turn
/* Input */
.rotate { transform: rotate(180deg); }

/* Output */
.rotate { transform: rotate(.5turn); }

Zero Unit Removal

The plugin removes unnecessary units from zero values:

/* Input */
.box { margin: 0px 0em 0% 0pc; }

/* Output */
.box { margin: 0 0 0 0; }

Precision Control

When precision is set to a number, pixel values are rounded to that many decimal places:

/* Input with precision: 2 */
.element { width: 6.66667px; }

/* Output */
.element { width: 6.67px; }

Opacity Clamping

The plugin ensures opacity and shape-image-threshold values stay within the valid 0-1 range:

/* Input */
.element { opacity: 1.5; }

/* Output */
.element { opacity: 1; }

Browser Compatibility

The plugin respects browserslist configuration for IE11 compatibility. Certain properties retain percentage units on zero values when IE11 is targeted:

  • max-height, height, min-width retain 0% instead of 0 for IE11 compatibility
// Target IE11 specifically
postcss([convertValues({
  overrideBrowserslist: ["ie 11"]
})]);

Property Exclusions

The plugin automatically skips processing for:

  • Flex properties: Properties containing "flex" maintain their original units
  • Custom properties: CSS variables (starting with --) are not processed
  • Percentage-only properties: descent-override, ascent-override, font-stretch, size-adjust, line-gap-override
  • Special zero cases: stroke-dashoffset, stroke-width, line-height retain units even when zero
  • IE11 percentage preservation: max-height, height, min-width retain 0% instead of 0 when IE11 is targeted
  • Function contexts: Within calc(), color-mix(), min(), max(), clamp(), hsl(), hsla(), hwb(), linear() functions, percentages are preserved
  • Keyframe properties: border-image-width, stroke-dasharray in @keyframes contexts retain percentage units

Types

interface Plugin {
  postcssPlugin: string;
  prepare(result: Result): {
    OnceExit(css: Root): void;
  };
}

interface Result {
  opts?: {
    file?: string;
    from?: string;
    stats?: any;
    env?: string;
    path?: string;
  };
}

interface Root {
  walkDecls(callback: (decl: Declaration) => void): void;
}

interface Declaration {
  prop: string;
  value: string;
  parent?: any;
}