postcss-logical-polyfill

A PostCSS plugin that transforms CSS logical properties into physical properties with appropriate direction selectors, enabling backward compatibility for older browsers.

Quick Start

Installation

# Using npm
npm install postcss-logical-polyfill --save-dev
# Using pnpm
pnpm add -D postcss-logical-polyfill
# Using yarn
yarn add -D postcss-logical-polyfill

Basic Usage

Playground

Full document

// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-logical-polyfill')()
  ]
}

Example Transformation

Input CSS:

.container {
  margin-inline: 1rem;
  padding-block: 2rem;
  border-inline-start: 2px solid blue;
}

Output CSS:

.container {
  margin-left: 1rem;
  margin-right: 1rem;
  padding-top: 2rem;
  padding-bottom: 2rem;
}
[dir="ltr"] .container {
  border-left: 2px solid blue;
}
[dir="rtl"] .container {
  border-right: 2px solid blue;
}

Key Features

• 🔄 Polyfill Direction: Transforms logical properties → physical properties (reverse of most tools)
• 🎯 Smart Generation: Creates both LTR and RTL versions automatically
• ⚡ Optimized Output: Block-direction properties generate single rules (no duplication)
• 🔗 Extended Support: Includes scroll properties and logical values via integrated shim
• 🧪 Experimental Features: Linear gradient logical directions and draft CSS specs
• 🎛️ Configurable: Custom selectors and output order control
• 🏗️ Framework Ready: Works with any build tool or CSS framework

Why Use This Plugin?

While modern browsers support CSS logical properties, older browsers don't. This plugin acts as a polyfill, converting your modern logical properties to physical properties that work everywhere, while preserving the directional behavior for international layouts.

Perfect for:

• ✅ Supporting older browsers while using modern CSS
• ✅ Gradual migration from physical to logical properties
• ✅ RTL/LTR internationalization
• ✅ Framework integration with directional layouts

Installation

# Using npm
npm install postcss-logical-polyfill --save-dev

# Using pnpm
pnpm add -D postcss-logical-polyfill

# Using yarn
yarn add -D postcss-logical-polyfill

What It Does

This plugin transforms CSS Logical Properties into physical properties with appropriate direction selectors for browser compatibility. It intelligently processes:

• All standard logical properties (margin, padding, border, inset, sizing, etc.)
• Logical values (float: inline-start, clear: inline-end, resize: block)
• Scroll properties (scroll-margin, scroll-padding)
• Experimental features (linear-gradient logical directions)
• Both scoped and unscoped logical properties

➡️ Complete supported properties list

Configuration

Basic Options

const logicalPolyfill = require('postcss-logical-polyfill');

postcss([
  logicalPolyfill({
    // Direction selectors (default shown)
    rtl: { selector: '[dir="rtl"]' },
    ltr: { selector: '[dir="ltr"]' },
    
    // Output order for unscoped properties
    outputOrder: 'ltr-first'  // or 'rtl-first'
  })
])

➡️ Complete configuration guide

Example Transformation

Input CSS:

/* Unscoped logical properties - will generate both LTR and RTL versions */
.container {
  margin-inline: 1rem;
  padding-inline-start: 1rem;
}

/* Block-direction properties - Generate single optimized rule */
.content {
  margin-block: 2rem;
  padding-block-start: 1rem;
}

/* Extended logical properties via shim system */
.scroll-area {
  scroll-margin-inline: 10px;
  float: inline-start;
}

/* Experimental: Linear gradient logical directions */
.gradient-element {
  background: linear-gradient(to inline-end, red, blue);
}

Output CSS:

.container {
  margin-left: 1rem;
  margin-right: 1rem;
}
[dir="ltr"] .container {
  padding-left: 1rem;
}
[dir="rtl"] .container {
  padding-right: 1rem;
}

/* Block-direction properties - Single optimized rule */
.content {
  margin-top: 2rem;
  margin-bottom: 2rem;
  padding-top: 1rem;
}

/* Extended logical properties transformed */
.scroll-area {
  scroll-margin-left: 10px;
  scroll-margin-right: 10px;
}
[dir="ltr"] .scroll-area {
  float: left;
}
[dir="rtl"] .scroll-area {
  float: right;
}

/* Experimental features automatically enabled */
[dir="ltr"] .gradient-element {
  background: linear-gradient(to right, red, blue);
}
[dir="rtl"] .gradient-element {
  background: linear-gradient(to left, red, blue);
}

How It Works

This plugin intelligently processes CSS through a 7-phase optimization pipeline:

1. 🔍 Detection: Identifies logical properties and existing direction selectors
2. 🎯 Classification: Separates block-direction, inline-direction, and mixed properties
3. 🔄 Transformation: Converts logical to physical properties based on direction context
4. 🎯 Selector Application: Adds appropriate direction selectors when needed
5. 🔧 Optimization: Merges rules and eliminates redundant declarations
6. 🎯 Smart Priority: Implements rightmost selector precedence for predictable behavior
7. ✨ Output: Generates clean, optimized CSS for maximum compatibility

➡️ Detailed technical explanation

Getting Started

Installation

npm install postcss-logical-polyfill --save-dev

Basic Setup

// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-logical-polyfill')()
  ]
}

Build Tool Integration

➡️ Integration guides for Webpack, Vite, Next.js, and more

Important Notes

HTML Direction Attribute Required

You must set the dir attribute on your HTML for the generated CSS to work:

<html dir="ltr">  <!-- For left-to-right layouts -->
<html dir="rtl">  <!-- For right-to-left layouts -->

Without the dir attribute, the generated [dir="ltr"] and [dir="rtl"] selectors won't match.

Custom Selectors

You can configure custom direction selectors for your framework:

logicalPolyfill({
  ltr: { selector: '.ltr' },
  rtl: { selector: '.rtl' }
})

➡️ Complete usage guide and best practices

Examples

This package includes ready-to-run examples for different build systems and use cases.

# View all available examples
ls examples/

# Run specific examples
cd examples/basic && npx tsx process.ts
cd examples/webpack && npx tsx process.ts
cd examples/sass && npx tsx process.ts

# Run all examples at once
pnpm run examples

Available examples:

• Basic: Plain CSS with PostCSS
• Build Tools: Webpack integration
• Preprocessors: SASS and LESS integration
• Configuration: Output order and selector priority
• CLI: PostCSS command-line usage

➡️ View all examples

Troubleshooting

Having issues? Check our troubleshooting guide for common problems and solutions.

➡️ Complete troubleshooting guide

Documentation

• 📖 Full Documentation - Complete documentation site built with Astro Starlight
• 🚀 Getting Started Guide - Quick start and installation
• ⚙️ Configuration - Configuration options and framework integration
• 📋 Supported Properties - Complete reference of all supported logical properties
• 🔧 How It Works - Technical details about the processing pipeline
• 🎮 Interactive Playground - Try the plugin online with live preview

Learn More

• CSS Logical Properties and Values (MDN) - Official documentation and browser support information

Requirements

• Node.js 16.0.0 or later
• PostCSS 8.0.0 or later

Contributing

Contributions are welcome! Please see our contributing guidelines for details.

Credits

This plugin wraps and extends postcss-logical to provide polyfill functionality.

License

MIT