PostCSS Normalize Positions

PostCSS Normalize Positions is a PostCSS plugin that normalizes CSS position keyword values by converting them to their equivalent length values. It transforms CSS background-position and position properties from human-readable keywords like 'bottom left' to more compact percentage or pixel values like '0 100%', optimizing CSS file size while maintaining the same visual appearance.

Package Information

• Package Name: postcss-normalize-positions
• Package Type: npm
• Language: JavaScript
• Installation: npm install postcss-normalize-positions
• Peer Dependencies: PostCSS ^8.4.32

Core Imports

const postcssNormalizePositions = require('postcss-normalize-positions');

For modern ESM environments:

import postcssNormalizePositions from 'postcss-normalize-positions';

TypeScript:

import postcssNormalizePositions from 'postcss-normalize-positions';
import type { Plugin } from 'postcss';

const plugin: Plugin = postcssNormalizePositions();

Basic Usage

const postcss = require('postcss');
const postcssNormalizePositions = require('postcss-normalize-positions');

// Apply the plugin to CSS
const result = await postcss([
  postcssNormalizePositions()
])
.process(css, { from: undefined });

console.log(result.css);

Example transformation:

Input CSS:

div {
  background-position: bottom left;
}

Output CSS:

div {
  background-position: 0 100%;
}

Capabilities

Plugin Creator Function

Creates a PostCSS plugin instance that normalizes position keyword values in CSS declarations.

/**
 * Creates a PostCSS plugin instance for normalizing position values
 * @returns {Plugin} PostCSS plugin object that processes CSS during the OnceExit phase
 */
function postcssNormalizePositions(): Plugin;

The plugin creator function has a marker property that identifies it as a PostCSS plugin:

postcssNormalizePositions.postcss = true;

Plugin Object

The returned plugin object implements the PostCSS plugin interface:

interface Plugin {
  /** Plugin name identifier */
  postcssPlugin: "postcss-normalize-positions";
  /** Main plugin processing function that runs once after all other processing */
  OnceExit(css: Root): void;
}

Supported CSS Properties

The plugin processes the following CSS properties and their values:

• background (background shorthand property)
• background-position
• perspective-origin
• Vendor-prefixed perspective-origin properties (e.g., -webkit-perspective-origin)

Position Value Transformations

The plugin performs the following keyword-to-value transformations:

Single Keywords

• center → 50%
• left → 0
• right → 100%
• top → 0
• bottom → 100%

Two-Value Combinations

• left bottom → 0 100%
• right top → 100% 0
• center left → 0
• center right → 100%
• top center → 50% 0
• bottom center → 50% 100%

Mixed Value Handling

• 30% center → 30% (removes redundant center)
• Preserves existing percentage and pixel values
• Maintains three-value syntax without transformation

Preservation Rules

The plugin preserves certain values without transformation:

CSS Functions

• Math functions: calc(), min(), max(), clamp()
• Variable functions: var(), env(), constant()

Complex Syntax

• Background size values (after / separator)
• Three-value position syntax
• Multiple background declarations (comma-separated)

Performance Features

• Internal caching of transformed values
• Single-pass processing with OnceExit hook
• Efficient value parsing using postcss-value-parser

Plugin Behavior

• Processes CSS declarations during PostCSS's OnceExit phase
• Uses internal Map cache to avoid re-processing identical values
• Safely handles malformed or invalid position values by leaving them unchanged
• Compatible with all PostCSS plugin ordering configurations

Usage Examples

Basic PostCSS Configuration

// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-normalize-positions')(),
    // other plugins...
  ]
};

With Build Tools

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'postcss-loader',
            options: {
              postcssOptions: {
                plugins: [
                  require('postcss-normalize-positions')(),
                ]
              }
            }
          }
        ]
      }
    ]
  }
};

Programmatic Usage

const postcss = require('postcss');
const normalizePositions = require('postcss-normalize-positions');

async function processCSS(inputCSS) {
  const result = await postcss([
    normalizePositions()
  ]).process(inputCSS, { from: undefined });
  
  return result.css;
}

// Example usage
const css = `
  .hero {
    background: url(hero.jpg) center center no-repeat;
    background-position: right bottom;
  }
  .sidebar {
    perspective-origin: left top;
  }
`;

processCSS(css)
  .then(optimizedCSS => console.log(optimizedCSS));

Output:

.hero {
  background: url(hero.jpg) 50% no-repeat;
  background-position: 100% 100%;
}
.sidebar {
  perspective-origin: 0 0;
}