PostCSS Logical Properties and Values [][PostCSS]

npm install postcss-logical --save-dev

[PostCSS Logical Properties and Values] lets you use logical, rather than physical, direction and dimension mappings in CSS, following the [CSS Logical Properties and Values] specification.

``css
.element {
block-size: 100px;
max-inline-size: 400px;
inline-size: 200px;
padding-block: 10px 20px;
margin-inline: auto;
border-block-width: 2px;
border-block-style: solid;
}

/ becomes /

.element {
height: 100px;
max-width: 400px;
width: 200px;
padding-top: 10px;
padding-bottom: 20px;
margin-left: auto;
margin-right: auto;
border-top-width: 2px;
border-bottom-width: 2px;
border-top-style: solid;
border-bottom-style: solid;
}
`

Usage

Add [PostCSS Logical Properties and Values] to your project:

`bash
npm install postcss postcss-logical --save-dev
`

Use it as a [PostCSS] plugin:

`js
const postcss = require('postcss');
const postcssLogical = require('postcss-logical');

postcss([
postcssLogical(/ pluginOptions /)
]).process(YOUR_CSS /, processOptions /);
`

Options

$3

The blockDirection and inlineDirection options allow you to specify the direction of the block and inline axes. The default values are top-to-bottom and left-to-right respectively, which would match any latin language.

You should tweak these values so that they are specific to your language and writing mode.

`js
postcssLogical({
blockDirection: 'right-to-left',
inlineDirection: 'top-to-bottom'
})
`

`css
.element {
block-size: 100px;
max-inline-size: 400px;
inline-size: 200px;
padding-block: 10px 20px;
margin-inline: auto;
border-block-width: 2px;
border-block-style: solid;
}

/ becomes /

.element {
width: 100px;
max-height: 400px;
height: 200px;
padding-right: 10px;
padding-left: 20px;
margin-top: auto;
margin-bottom: auto;
border-right-width: 2px;
border-left-width: 2px;
border-right-style: solid;
border-left-style: solid;
}
`

Each direction must be one of the following:

- top-to-bottom
- bottom-to-top
- left-to-right
- right-to-left

You can't mix two vertical directions or two horizontal directions so for example top-to-bottom and right-to-left are valid, but top-to-bottom and bottom-to-top are not.

Please do note that text-align won't be transformed if inlineDirection becomes vertical.

$3

The ignoreCustomProperties option allows you to ignore any properties containing var().
postcss-logical assumes that all custom properties are single value (e.g. --foo: 10px;) and will assign these to physical properties as fallbacks for logical properties.

This will produce broken declarations when your custom properties contain multiple values instead (e.g. --foo: 1px 2px;).

`css
:root {
--inset-a: 10px;
}

.foo {
inset: var(--inset-a);
}

:root {
--inset-b: 1px 2px 3px 4px;
}

.bar {
inset: var(--inset-b);
}

/ becomes /

:root {
--inset-a: 10px;
}

.foo {
top: var(--inset-a);
right: var(--inset-a);
bottom: var(--inset-a);
left: var(--inset-a);
}

:root {
--inset-b: 1px 2px 3px 4px;
}

.bar {
top: var(--inset-b);
right: var(--inset-b);
bottom: var(--inset-b);
left: var(--inset-b);
}
`

With ignoreCustomProperties set to true:

`css
:root {
--inset-a: 10px;
}

.foo {
inset: var(--inset-a);
}

:root {
--inset-b: 1px 2px 3px 4px;
}

.bar {
inset: var(--inset-b);
}

/ becomes /

:root {
--inset-a: 10px;
}

.foo {
inset: var(--inset-a);
}

:root {
--inset-b: 1px 2px 3px 4px;
}

.bar {
inset: var(--inset-b);
}
``

[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
[css-url]: https://cssdb.org/#logical-properties-and-values
[discord]: https://discord.gg/bUadyRwkJS
[npm-url]: https://www.npmjs.com/package/postcss-logical

[PostCSS]: https://github.com/postcss/postcss
[PostCSS Logical Properties and Values]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-logical
[CSS Logical Properties and Values]: https://www.w3.org/TR/css-logical-1/