API Reference

This reference documents all configuration options and methods available in postcss-logical-polyfill.

Plugin Options

The plugin accepts a LogicalPolyfillOptions object with the following properties:

rtl

• Type: object
• Description: Configuration for RTL (Right-to-Left) direction

rtl.selector

• Type: string
• Default: '[dir="rtl"]'
• Description: CSS selector used to target RTL content

require('postcss-logical-polyfill')({
  rtl: {
    selector: '[dir="rtl"]'
  }
})

// Input CSS
.element { margin-inline-start: 1rem; }

// Output CSS
[dir="ltr"] .element { margin-left: 1rem; }
[dir="rtl"] .element { margin-right: 1rem; }

Examples:

• '[dir="rtl"]' - Attribute selector (default)
• ':dir(rtl)' - CSS4 direction pseudo-class
• '.rtl' - Class-based approach

ltr

• Type: object
• Description: Configuration for LTR (Left-to-Right) direction

ltr.selector

• Type: string
• Default: '[dir="ltr"]'
• Description: CSS selector used to target LTR content

require('postcss-logical-polyfill')({
  ltr: {
    selector: '[dir="ltr"]'
  }
})

outputOrder

• Type: 'ltr-first' | 'rtl-first'
• Default: 'ltr-first'
• Description: Controls the order in which LTR and RTL rules are output in the generated CSS

// LTR rules first (default)
require('postcss-logical-polyfill')({
  outputOrder: 'ltr-first'
})

// RTL rules first
require('postcss-logical-polyfill')({
  outputOrder: 'rtl-first'
})

This can be useful for CSS specificity control or debugging purposes.

Property Transformations

Margin Properties

Logical Property	LTR Physical	RTL Physical
margin-inline	margin-left, margin-right	margin-left, margin-right
margin-inline-start	margin-left	margin-right
margin-inline-end	margin-right	margin-left
margin-block	margin-top, margin-bottom	margin-top, margin-bottom
margin-block-start	margin-top	margin-top
margin-block-end	margin-bottom	margin-bottom

Padding Properties

Logical Property	LTR Physical	RTL Physical
padding-inline	padding-left, padding-right	padding-left, padding-right
padding-inline-start	padding-left	padding-right
padding-inline-end	padding-right	padding-left
padding-block	padding-top, padding-bottom	padding-top, padding-bottom
padding-block-start	padding-top	padding-top
padding-block-end	padding-bottom	padding-bottom

Border Properties

Logical Property	LTR Physical	RTL Physical
border-inline	border-left, border-right	border-left, border-right
border-inline-start	border-left	border-right
border-inline-end	border-right	border-left
border-block	border-top, border-bottom	border-top, border-bottom
border-block-start	border-top	border-top
border-block-end	border-bottom	border-bottom

Border Radius Properties

Logical Property	LTR Physical	RTL Physical
border-start-start-radius	border-top-left-radius	border-top-right-radius
border-start-end-radius	border-top-right-radius	border-top-left-radius
border-end-start-radius	border-bottom-left-radius	border-bottom-right-radius
border-end-end-radius	border-bottom-right-radius	border-bottom-left-radius

Inset Properties

Logical Property	LTR Physical	RTL Physical
inset-inline	left, right	left, right
inset-inline-start	left	right
inset-inline-end	right	left
inset-block	top, bottom	top, bottom
inset-block-start	top	top
inset-block-end	bottom	bottom

Size Properties

Logical Property	Physical Equivalent
block-size	height
inline-size	width
min-block-size	min-height
min-inline-size	min-width
max-block-size	max-height
max-inline-size	max-width

Overflow Properties (Experimental)

Logical Property	Physical Equivalent
overflow-block	overflow-y
overflow-inline	overflow-x

Logical Values

The plugin also transforms logical values in certain properties:

Property	Logical Value	LTR Physical	RTL Physical
float	inline-start	left	right
float	inline-end	right	left
clear	inline-start	left	right
clear	inline-end	right	left
text-align	start	left	right
text-align	end	right	left

Usage Examples

Basic Usage

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

postcss([
  logicalPolyfill({
    preserve: false,
    dir: 'ltr'
  })
])
.process(css)
.then(result => {
  console.log(result.css)
})

With Async/Await

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

async function transformCSS(css) {
  const result = await postcss([
    logicalPolyfill()
  ]).process(css, { from: undefined })

  return result.css
}

Build Tool Integration

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'postcss-loader',
            options: {
              postcssOptions: {
                plugins: [
                  ['postcss-logical-polyfill', {
                    preserve: process.env.NODE_ENV === 'development',
                    experimental: true
                  }]
                ]
              }
            }
          }
        ]
      }
    ]
  }
}

Plugin Methods

process()

The main processing method that transforms logical properties to physical properties.

Parameters:

• root (PostCSS Root): The PostCSS AST root node
• options (Object): Plugin configuration options

Returns: Modified PostCSS AST with transformed properties

Internal Methods

These methods are used internally by the plugin:

transformProperty(prop, value, dir)

Transforms a single logical property to its physical equivalent.

generateSelectors(selector, dir)

Generates direction-specific selectors when needed.

isLogicalProperty(prop)

Checks if a property is a logical property that should be transformed.

Browser Support

The plugin generates CSS that supports:

• Modern browsers: Use native logical properties when available
• Legacy browsers: Fall back to physical properties
• IE11: Full support with physical properties only

Feature Detection

When supports: true is enabled, the plugin generates progressive enhancement CSS:

/* Modern browsers use logical properties */
.element {
  margin-inline: 1rem;
}

/* Legacy browsers get physical properties */
@supports not (margin-inline: 1rem) {
  .element {
    margin-left: 1rem;
    margin-right: 1rem;
  }
}

TypeScript Support

The plugin includes TypeScript definitions:

import postcss from 'postcss'
import logicalPolyfill, { Options } from 'postcss-logical-polyfill'

const options: Options = {
  preserve: false,
  dir: 'ltr',
  supports: true,
  experimental: false
}

const processor = postcss([logicalPolyfill(options)])

Error Handling

The plugin handles various edge cases and provides informative warnings:

• Invalid logical property values
• Conflicting logical and physical properties
• Unsupported property combinations

// Warning example
console.warn('postcss-logical-polyfill: Conflicting properties detected')

Performance Considerations

• Caching: The plugin caches transformed selectors for better performance
• Selective Processing: Only processes rules that contain logical properties
• Minimal Output: Generates only necessary fallbacks when using @supports

For large projects, consider:

1. Using preserve: false in production
2. Enabling supports: true for progressive enhancement
3. Processing only relevant CSS files