PostCSS RTLCSS

PostCSS plugin to build Cascading Style Sheets (CSS) with Left-To-Right (LTR) and Right-To-Left (RTL) rules using RTLCSS. RTLCSS allows one to flip an entire CSS file with the intention of using the original CSS for one direction and the new generated one for the other. What PostCSS RTLCSS does, is to create a single CSS file with both directions or to create a minimal CSS file only with the flipped rules with the intention of overriding the main one.

Playground Demo

https://elchininet.github.io/postcss-rtlcss/

Install

npm

1npm install postcss-rtlcss --save-dev

pnpm

1pnpm add -D postcss-rtlcss

yarn

1yarn add postcss-rtlcss -D

Basic usage

Usage with commonJS

1const postcss = require('postcss');
2const postcssRTLCSS = require('postcss-rtlcss');
3const { Mode, Source } = require('postcss-rtlcss/options');
4
5const options = { ... available options ... };
6const result = postcss([
7    postcssRTLCSS(options)
8]).process(cssInput);
9
10const rtlCSS = result.css;

Usage with ES6 modules

1import postcss from 'postcss';
2import postcssRTLCSS from 'postcss-rtlcss';
3import { Mode, Source } from 'postcss-rtlcss/options';
4
5const options = { ... available options ... };
6const result = postcss([
7    postcssRTLCSS(options)
8]).process(cssInput);
9
10const rtlCSS = result.css;

Usage in Webpack with postcss-loader

1rules: [
2    {
3        test: /\.css$/,
4        use: [
5            { loader: 'style-loader' },
6            { loader: 'css-loader' },
7            {
8                loader: 'postcss-loader',
9                options: {
10                    postcssOptions: {
11                        plugins: [
12                            postcssRTLCSS(options)
13                        ]
14                    }
15                }
16            }
17        ]
18    }
19]

Examples

Input

1.test1, .test2 {
2    background-color: #FFF;
3    background-position: 10px 20px;
4    border-radius: 0 2px 0 8px;
5    color: #666;
6    padding-right: 20px;
7    text-align: left;
8    transform: translate(-50%, 50%);
9    width: 100%;
10}
11
12.test3 {
13    direction: ltr;
14    margin: 1px 2px 3px;
15    padding: 10px 20px;
16    text-align: center;
17}

Output using the combined mode (default and recommended)

This is the recommended method, it will generate more CSS code because each direction will have their specific prefixed rules but it is the safest option.

1.test1, .test2 {
2    background-color: #FFF;
3    background-position: 10px 20px;
4    color: #666;
5    width: 100%;
6}
7
8[dir="ltr"] .test1, [dir="ltr"] .test2 {
9    border-radius: 0 2px 0 8px;
10    padding-right: 20px;
11    text-align: left;
12    transform: translate(-50%, 50%);
13}
14
15[dir="rtl"] .test1, [dir="rtl"] .test2 {
16    border-radius: 2px 0 8px 0;
17    padding-left: 20px;
18    text-align: right;
19    transform: translate(50%, 50%);
20}
21
22.test3 {
23    margin: 1px 2px 3px;
24    padding: 10px 20px;
25    text-align: center;
26}
27
28[dir="ltr"] .test3 {
29    direction: ltr;
30}
31
32[dir="rtl"] .test3 {
33    direction: rtl;
34}

Output using the override mode

[!IMPORTANT] This method is not recommended, check below why

This is one of the alternative methods to override. It will generate less code because it lets the main rule intact most of the time and generates shorter specific rules to override the properties that are affected by the direction of the text.

1.test1, .test2 {
2    background-color: #FFF;
3    background-position: 10px 20px;
4    border-radius: 0 2px 0 8px;
5    color: #666;
6    padding-right: 20px;
7    text-align: left;
8    transform: translate(-50%, 50%);
9    width: 100%;
10}
11
12[dir="rtl"] .test1, [dir="rtl"] .test2 {
13    border-radius: 2px 0 8px 0;
14    padding-right: 0;
15    padding-left: 20px;
16    text-align: right;
17    transform: translate(50%, 50%);
18}
19
20.test3 {
21    direction: ltr;
22    margin: 1px 2px 3px;
23    padding: 10px 20px;
24    text-align: center;
25}
26
27[dir="rtl"] .test3 {
28    direction: rtl;
29}

Output using the diff mode

[!IMPORTANT] This method is not recommended, check below why

This is the second alternative method to override. It generates the minimum amount of code because it only outputs the rules that have been flipped and without prefixing them. The intention of this method is to generate a separate stylesheet file that will be loaded on top of the original one to override those rules that need to be flipped in certain direction.

1.test1, .test2 {
2    border-radius: 2px 0 8px 0;
3    padding-right: 0;
4    padding-left: 20px;
5    text-align: right;
6    transform: translate(50%, 50%);
7}
8
9.test3 {
10    direction: rtl;
11}

Disadvantages of the two methods to override

1. Some directives as /*rtl:freeze*/, /*rtl:begin:freeze*/ and /*rtl:end:freeze*/ do not work with these methods
2. They can override a property that is coming from another class if multiple classes are used at the same time. Take a look at the next HTML and CSS codes:

1<div class="test1 test2">
2    This is an example
3</div>    

1.test1 {
2    background: #666;
3    color: #FFF;
4    padding: 20px;
5}
6
7.test2 {
8    padding-right: 10px;
9}

Using the combined method, the generated code will be the next one:

1.test1 {
2    background: #666;
3    color: #FFF;
4    padding: 20px;
5}
6
7[dir="ltr"] .test2 {
8    padding-right: 10px;
9}
10
11[dir="rtl"] .test2 {
12    padding-left: 10px;
13}

So, the div will have a padding of 20px 10px 20px 20px in LTR and 20px 20px 20px 10px in RTL. Everything will work as expected here.

However, using the override method the generated code will be the next one:

1.test1 {
2    background: #666;
3    color: #FFF;
4    padding: 20px;
5}
6
7.test2 {
8    padding-right: 10px;
9}
10
11[dir="rtl"] .test2 {
12    padding-right: 0;
13    padding-left: 10px;
14}

And using the diff method the generated code will be the next one:

1.test2 {
2    padding-right: 0;
3    padding-left: 10px;
4}

Now the div has a padding of 20px 10px 20px 20px in LTR and 20px 0 20px 10px in RTL, because when the class test2 is overriden, it is not taken into account that it could be used with test1 having the same properties. The workaround, in this case, is to provide the property that has been inherited:

1.test1 {
2    background: #666;
3    color: #FFF;
4    padding: 20px;
5}
6
7.test2 {
8    padding-left: 20px;
9    padding-right: 10px;
10}

So, using the override method the generated code will be:

1.test1 {
2    background: #666;
3    color: #FFF;
4    padding: 20px;
5}
6
7.test2 {
8    padding-left: 20px;
9    padding-right: 10px;
10}
11
12[dir="rtl"] .test2 {
13    padding-right: 20px;
14    padding-left: 10px;
15}

And using the diff method the generated code will be:

1.test2 {
2    padding-right: 20px;
3    padding-left: 10px;
4}

Plugin Options

All the options are optional, and a default value will be used if any of them is omitted or the type or format of them is wrong

Option	Type	Default	Description
mode	Mode (string)	Mode.combined	Mode of generating the final CSS rules
ltrPrefix	string or string[]	[dir="ltr"]	Prefix to use in the left-to-right CSS rules
rtlPrefix	string or string[]	[dir="rtl"]	Prefix to use in the right-to-left CSS rules
bothPrefix	string or string[]	[dir]	Prefix to create a new rule that affects both directions when the specificity of the ltr or rtl rules will override its declarations
prefixSelectorTransformer	function	null	Transform function to have more control over the selectors prefixing logic
safeBothPrefix	boolean	false	Add the bothPrefix to those declarations that can be affected by the direction to avoid them being overridden by specificity
ignorePrefixedRules	boolean	true	Ignores rules that have been prefixed with some of the prefixes contained in ltrPrefix, rtlPrefix, or bothPrefix
source	Source (string)	Source.ltr	The direction from which the final CSS will be generated
processUrls	boolean	false	Change the strings in URLs using the string map
processRuleNames	boolean	false	Swap two rules containing no directional properties if they match any entry in stringMap when the direction changes
processKeyFrames	boolean	false	Flip keyframe animations
processEnv	boolean	true	When processEnv is false, it prevents flipping agent-defined environment variables (safe-area-inset-left and safe-area-inset-right)
useCalc	boolean	false	Flips background-position-x and transform-origin properties if they are expressed in length units using calc
stringMap	PluginStringMap[]	Check below	An array of strings maps that will be used to make the replacements of the declarations' URLs and to match the names of the rules if processRuleNames is true
greedy	boolean	false	When greedy is true, the matches of stringMap will not take into account word boundaries
aliases	Record<string, string>	{}	A strings map to treat some declarations as others
processDeclarationPlugins	DeclarationPlugin[]	[]	Plugins applied when processing CSS declarations
runOnExit	boolean	false	Defines which visitor will be used to execute the plugin. If it is false (default value), Once will be used, but if it is true, OnceExit will be used instead.

---

mode

The mode option has been explained in the Output using the combined mode, the Output using the override mode, and the Output using the diff mode sections. To avoid using magic strings, the package exposes an object with these values, but it is possible to use strings values anyway:

1import postcss from 'postcss';
2import postcssRTLCSS from 'postcss-rtlcss';
3import { Mode } from 'postcss-rtlcss/options';
4
5const input = '... css code ...';
6const optionsCombined = { mode: Mode.combined }; // This is the default value
7const optionsOverride = { mode: Mode.override };
8const optionsDiff = { mode: Mode.diff };
9
10const outputCombined = postcss([
11    postcssRTLCSS(optionsCombined)
12]).process(input);
13
14const outputOverride = postcss([
15    postcssRTLCSS(optionsOverride)
16]).process(input);
17
18const outputDiff = postcss([
19    postcssRTLCSS(optionsDiff)
20]).process(input);

---

ltrPrefix and rtlPrefix

These two options manage the prefix strings for each direction. They can be strings or arrays of strings:

input

1.test1, .test2 {
2    left: 10px;
3}
4
5.test3,
6.test4 {
7    text-align: left;
8}

Using strings

1const options = {
2    ltrPrefix: '.ltr',
3    rtlPrefix: '.rtl'
4};

output

1.ltr .test1, .ltr .test2 {
2    left: 10px;
3}
4
5.rtl .test1, .rtl .test2 {
6    right: 10px;
7}
8
9.ltr .test3,
10.ltr .test4 {
11    text-align: left;
12}
13
14.rtl .test3,
15.rtl .test4 {
16    text-align: right;
17}

Using arrays of strings

1const options = {
2    ltrPrefix: ['[dir="ltr"]', '.ltr'],
3    rtlPrefix: ['[dir="rtl"]', '.rtl']
4};

output

1[dir="ltr"] .test1, .ltr .test1, [dir="ltr"] .test2, .ltr .test2 {
2    left: 10px;
3}
4
5[dir="rtl"] .test1, .rtl .test1, [dir="rtl"] .test2, .rtl .test2 {
6    right: 10px;
7}
8
9[dir="ltr"] .test3,
10.ltr .test3,
11[dir="ltr"] .test4,
12.ltr .test4 {
13    text-align: left;
14}
15
16[dir="rtl"] .test3,
17.rtl .test3,
18[dir="rtl"] .test4,
19.rtl .test4 {
20    text-align: right;
21}

---

bothPrefix

This prefix will be used in some specific cases in which a ltr or rtl rule will override declarations located in the main rule due to specificity. Consider the next example using the option processUrls as true:

1.test1 {
2    background: url('icons/ltr/arrow.png');
3    background-size: 10px 20px;
4    width: 10px;
5}

The generated CSS would be:

1.test1 {
2    background-size: 10px 20px;
3    width: 10px;
4}
5
6[dir="ltr"] .test1 {
7    background: url('icons/ltr/arrow.png');
8}
9
10[dir="rtl"] .test1 {
11    background: url('icons/rtl/arrow.png');
12}

In the previous case, the background-size property has been overridden by the background one. Even if we change the order of the rules, the last ones have a higher specificity, so they will rule over the first one.

To solve this, another rule will be created at the end using the bothPrefix parameter:

1.test1 {
2    width: 10px;
3}
4
5[dir="ltr"] .test1 {
6    background: url('icons/ltr/arrow.png');
7}
8
9[dir="rtl"] .test1 {
10    background: url('icons/rtl/arrow.png');
11}
12
13[dir] {
14    background-size: 10px 20px;
15}

And no matter the direction, the background-size property is respected.

---

prefixSelectorTransformer

This function will be used to transform the selectors and prefixing them at our will. The first parameter will be the prefix that will be used and the second the current selector:

[!NOTE]

• If the function doesn‘t return a string, the default prefixing logic will be used.
• If this function is used, be aware that rules using html, :root or ::view-transition will follow the custom prefixing logic. You should cover these cases.

input

1.test1 {
2    left: 10px;
3    padding-right: 5px;
4    padding-inline-end: 20px;
5}

If the prefixSelectorTransformer is not sent (default):

output

1[dir="ltr"] .test1 {
2    left: 10px;
3    padding-right: 5px;
4}
5
6[dir="rtl"] .test1 {
7    right: 10px;
8    padding-left: 5px;
9}
10
11[dir] .test1 {
12    padding-inline-end: 20px;
13}

Setting a prefixSelectorTransformer function

1const options = {
2    prefixSelectorTransformer: function (prefix, selector) {
3        if (prefix === '[dir]') {
4            return `.container > ${prefix} > ${selector}`;
5        }
6        return `${selector}${prefix}`;
7    }
8};

output

1.test1[dir="ltr"] {
2    left: 10px;
3    padding-right: 5px;
4}
5
6.test1[dir="rtl"] {
7    right: 10px;
8    padding-left: 5px;
9}
10
11.container > [dir] > .test1 {
12    padding-inline-end: 20px;
13}

---

safeBothPrefix

This option will add the boxPrefix option to those declarations that can be flipped, no matter if they are not overridden in the same rule. This avoids them being overridden by specificity of other flipped declarations contained in other rules. For example, let's consider that we have a div element with the next rules:

1<div class="test1 test2">
2    This is an example
3</div> 

1.test1 {
2    color: #FFF;
3    padding: 4px 10px 4px 20px;
4    width: 100%;
5}
6
7.test2 {
8    padding: 0;
9}

The expecting result is that the padding of the element becomes 0 as it has been reset by test2. With safeBothPrefix in false, the generated CSS will be:

1.test1 {
2    color: #FFF;
3    width: 100%;
4}
5
6[dir="ltr"] .test1 {
7    padding: 4px 10px 4px 20px;
8}
9
10[dir="rtl"] .test1 {
11    padding: 4px 20px 4px 10px;
12}
13
14.test2 {
15    padding: 0;
16}

The result is that the padding properties of test1 have more specificity than the same property in tes2, so it is not reset if both rules are applied at the same time. Let's check the result if safeBothPrefix is true:

1.test1 {
2    color: #FFF;
3    width: 100%;
4}
5
6[dir="ltr"] .test1 {
7    padding: 4px 10px 4px 20px;
8}
9
10[dir="rtl"] .test1 {
11    padding: 4px 20px 4px 10px;
12}
13
14[dir] .test2 {
15    padding: 0;
16}

As test2 has the same level of specificity as test1, now the result is that the padding is reset if both rules are used at the same time.

---

ignorePrefixedRules

This option is to ignore the rules that have been prefixed with one of the prefixes contained in ltrPrefix, rtlPrefix, or bothPrefix:

input

1[dir="ltr"] test {
2    left: 10px;
3}
4
5[dir="rtl"] test {
6    right: 10px;
7}

ignorePrefixedRules true

1const options = { ignorePrefixedRules: true }; // This is the default value

output

1[dir="ltr"] test {
2    left: 10px;
3}
4
5[dir="rtl"] test {
6    right: 10px;
7}

ignorePrefixedRules false

1const options = { ignorePrefixedRules: false };

output

1[dir="ltr"] [dir="ltr"] test {
2    left: 10px;
3}
4
5[dir="rtl"] [dir="ltr"] test {
6    right: 10px;
7}
8
9[dir="ltr"] [dir="rtl"] test {
10    right: 10px;
11}
12
13[dir="rtl"] [dir="rtl"] test {
14    left: 10px;
15}

---

source

This option manages if the conversion will be from LTR to RTL or vice versa.

input

1.test1, .test2 {
2    left: 10px;
3}

Using Source.ltr in combined mode

1import { Mode, Source } from 'postcss-rtlcss/options';
2
3const options = {
4    mode: Mode.combined,
5    source: Source.ltr // This is the default value
6};

output

1[dir="ltr"] .test1, [dir="ltr"] .test2 {
2    left: 10px;
3}
4
5[dir="rtl"] .test1, [dir="rtl"] .test2 {
6    right: 10px;
7}

Using Source.rtl in override mode

1import { Mode, Source } from 'postcss-rtlcss/options';
2
3const options = {
4    mode: Mode.override,
5    source: Source.rtl
6};

output

1.test1, .test2 {
2    left: 10px;
3}
4
5[dir="ltr"] .test1, [dir="ltr"] .test2 {
6    left: auto;
7    right: 10px;
8}

---

processUrls

This options manages if the strings of the URLs should be flipped taken into account the string map:

input

1.test1, .test2 {
2    background-image: url("./folder/subfolder/icons/ltr/chevron-left.png");
3    left: 10px;
4}

processUrls false

1const options = { processUrls: false }; // This is the default value

output

1.test1, .test2 {
2    background-image: url("./folder/subfolder/icons/ltr/chevron-left.png");
3}
4
5[dir="ltr"] .test1, [dir="ltr"] .test2 {
6    left: 10px;
7}
8
9[dir="rtl"] .test1, [dir="rtl"] .test2 {
10    right: 10px;
11}

processUrls true

1const options = { processUrls: true };

output

1[dir="ltr"] .test1, [dir="ltr"] .test2 {
2    background-image: url("./folder/subfolder/icons/ltr/chevron-left.png");
3    left: 10px;
4}
5
6[dir="rtl"] .test1, [dir="rtl"] .test2 {
7    background-image: url("./folder/subfolder/icons/rtl/chevron-right.png");
8    right: 10px;
9}

---

processRuleNames

If it is true, it swaps two rules containing no directional properties if they match any entry in stringMap when the direction changes

[!IMPORTANT] This option will not prefix those rules that have been processed already because they had directional properties.

input

1.test1-ltr {
2    color: #FFF;
3}
4
5.test2-left::before {
6    content: "\f007";
7}
8
9.test2-right::before {
10    content: "\f010";
11}

processRuleNames true

1const options = {
2    processRuleNames: true
3};

output

1/* This selector will not be processed because it doesn't have a counterpart */
2.test1-ltr {
3    color: #FFF;
4}
5
6[dir="ltr"] .test2-left::before {
7    content: "\f007";
8}
9
10[dir="rtl"] .test2-left::before {
11    content: "\f010";
12}
13
14[dir="ltr"] .test2-right::before {
15    content: "\f010";
16}
17
18[dir="rtl"] .test2-right::before {
19    content: "\f007";
20}

---

processKeyFrames

This option manages if the @keyframes animation rules should be flipped:

input

1.test1 {
2    animation: 5s flip 1s ease-in-out;
3    color: #FFF;
4}
5
6@keyframes flip {
7    from {
8        transform: translateX(100px);
9    }
10    to {
11        transform: translateX(0);
12    }
13}

processKeyFrames false

1const options = { processKeyFrames: false }; // This is the default value

output

1.test1 {
2    animation: 5s flip 1s ease-in-out;
3    color: #FFF;
4}
5
6@keyframes flip {
7    from {
8        transform: translateX(100px);
9    }
10    to {
11        transform: translateX(0);
12    }
13}

processKeyFrames true

1const options = { processKeyFrames: true };

output

1.test1 {
2    color: #FFF;
3}
4
5[dir="ltr"] .test1 {
6    animation: 5s flip-ltr 1s ease-in-out;
7}
8
9[dir="rtl"] .test1 {
10    animation: 5s flip-rtl 1s ease-in-out;
11}
12
13@keyframes flip-ltr {
14    from {
15        transform: translateX(100px);
16    }
17    to {
18        transform: translateX(0);
19    }
20}
21
22@keyframes flip-rtl {
23    from {
24        transform: translateX(-100px);
25    }
26    to {
27        transform: translateX(0);
28    }
29}

---

processEnv

This options manages if the agent-defined environment variables should be flipped:

input

1body {
2    padding:
3        env(safe-area-inset-top, 10px)
4        env(safe-area-inset-right, 20px)
5        env(safe-area-inset-bottom, 30px)
6        env(safe-area-inset-left, 40px)
7    ;
8}
9
10.test1 {
11    margin-right: env(safe-area-inset-right, 10px);
12    margin-left: env(safe-area-inset-left, 20px);
13}

processEnv true

1const options = { processEnv: true }; // This is the default value

output

1[dir=\\"ltr\\"] body {
2    padding:
3        env(safe-area-inset-top, 10px)
4        env(safe-area-inset-right, 20px)
5        env(safe-area-inset-bottom, 30px)
6        env(safe-area-inset-left, 40px)
7    ;
8}
9
10[dir=\\"rtl\\"] body {
11    padding:
12        env(safe-area-inset-top, 10px)
13        env(safe-area-inset-right, 40px)
14        env(safe-area-inset-bottom, 30px)
15        env(safe-area-inset-left, 20px);
16}
17
18[dir=\\"ltr\\"] .test1 {
19    margin-right: env(safe-area-inset-right, 10px);
20    margin-left: env(safe-area-inset-left, 20px);
21}
22
23[dir=\\"rtl\\"] .test1 {
24    margin-left: env(safe-area-inset-left, 10px);
25    margin-right: env(safe-area-inset-right, 20px);
26}

processEnv false

1const options = { processEnv: false };

output

1[dir=\\"ltr\\"] body {
2    padding:
3        env(safe-area-inset-top, 10px)
4        env(safe-area-inset-right, 20px)
5        env(safe-area-inset-bottom, 30px)
6        env(safe-area-inset-left, 40px)
7    ;
8}
9
10[dir=\\"rtl\\"] body {
11    padding:
12        env(safe-area-inset-top, 10px)
13        env(safe-area-inset-left, 40px)
14        env(safe-area-inset-bottom, 30px)
15        env(safe-area-inset-right, 20px);
16}
17
18[dir=\\"ltr\\"] .test1 {
19    margin-right: env(safe-area-inset-right, 10px);
20    margin-left: env(safe-area-inset-left, 20px);
21}
22
23[dir=\\"rtl\\"] .test1 {
24    margin-left: env(safe-area-inset-right, 10px);
25    margin-right: env(safe-area-inset-left, 20px);
26}

---

useCalc

When this option is enabled, it flips background-position-x and transform-origin properties if they are expressed in length units using calc:

input

1.test {
2    background-image: url("./folder/subfolder/icons/ltr/chevron-left.png");
3    background-position-x: 5px;
4    left: 10px;
5    transform-origin: 10px 20px;
6    transform: scale(0.5, 0.5);
7}

useCalc false

1const options = { useCalc: false }; // This is the default value

output

1.test {
2    background-image: url("./folder/subfolder/icons/ltr/chevron-left.png");
3    background-position-x: 5px;
4    transform-origin: 10px 20px;
5    transform: scale(0.5, 0.5);
6}
7
8[dir="ltr"] .test {
9    left: 10px;
10}
11
12[dir="rtl"] .test {
13    right: 10px;
14}

useCalc true

1const options = { useCalc: true };

output

1.test {
2    background-image: url("./folder/subfolder/icons/ltr/chevron-left.png");
3    transform: scale(0.5, 0.5);
4}
5
6[dir="ltr"] .test {
7    background-position-x: 5px;
8    left: 10px;
9    transform-origin: 10px 20px;
10}
11
12[dir="rtl"] .test {
13    background-position-x: calc(100% - 5px);
14    right: 10px;
15    transform-origin: calc(100% - 10px) 20px;
16}

---

stringMap

An array of strings maps that will be used to make the replacements of the declarations' URLs and to match rules selectors names if the processRuleNames option is true. The name parameter is optional, but if you want to override any of the default string maps, just add your own using the same name.

1// This is the default string map object
2const options = {
3    stringMap: [
4        {
5            name: 'left-right',
6            search : ['left', 'Left', 'LEFT'],
7            replace : ['right', 'Right', 'RIGHT']
8        },
9        {
10            name: 'ltr-rtl',
11            search  : ['ltr', 'Ltr', 'LTR'],
12            replace : ['rtl', 'Rtl', 'RTL'],
13        }
14    ]
15};

---

greedy

When greedy is true, the matches of the stringMap will not take into account word boundaries.

input

1.test1 {
2    background: url("icon-left.png");
3}
4
5.test2 {
6    background: url("icon-ultra.png");
7}

greedy false

1const options = {
2    processUrls: true,
3    greedy: false // This is the default value
4};

output

1[dir="ltr"] .test1 {
2    background: url("icon-left.png");
3}
4
5[dir="rtl"] .test1 {
6    background: url("icon-right.png");
7}
8
9.test2 {
10    background: url("icon-ultra.png");
11}

greedy true

1const options = {
2    processUrls: true,
3    greedy: true
4};

output

1[dir="ltr"] .test1 {
2    background: url("icon-left.png");
3}
4
5[dir="rtl"] .test1 {
6    background: url("icon-right.png");
7}
8
9[dir="ltr"] .test2 {
10    background: url("icon-ultra.png");
11}
12
13[dir="rtl"] .test2 {
14    background: url("icon-urtla.png");
15}

---

aliases

This property consists of a string map to treat some declarations as others, very useful to flip the values of CSS variables.

input

1:root {
2    --my-padding: 1rem 1rem 1.5rem 1.5rem;
3}
4
5.test {
6    padding: var(--my-padding);
7}

No aliases string map (default)

output

1:root {
2    --my-padding: 1rem 1rem 1.5rem 1.5rem;
3}
4
5.test {
6    padding: var(--my-padding);
7}

Set an aliases string map

1const options = {
2    aliases: {
3        '--my-padding': 'padding'
4    }
5};

output

1[dir="ltr"]:root {
2    --my-padding: 1rem 1rem 1.5rem 1.5rem;
3}
4
5[dir="rtl"]:root {
6    --my-padding: 1rem 1.5rem 1.5rem 1rem;
7}
8
9.test {
10    padding: var(--my-padding);
11}

---

processDeclarationPlugins

The intention of the processDeclarationPlugins option is to process the declarations to extend or override RTLCSS functionality. For example, we can avoid automatically flipping of background-potion.

input

1.test {
2    background-position: 0 100%;
3}

Convert 0 to 100% (default)

output

1.test {
2    background-position: 100% 100%;
3}

Set a plugin to avoid flipping

1const options = {
2	processDeclarationPlugins: [
3        {
4            name: 'avoid-flipping-background',
5            priority: 99, // above the core RTLCSS plugin which has a priority value of 100
6            processors: [{
7                expr: /(background|object)(-position(-x)?|-image)?$/i,
8                action: (prop, value) => ({prop, value})}
9            ]
10        }
11    ]
12};

output

1.test {
2    background-position: 0 100%;
3}

---

runOnExit

This option defines which PostCSS visitor will be used to execute the plugin. By default it is false, so the Once visitor will be used. If it is true, OnceExit will be used instead. Setting this option in true is useful if the plugin is used together with postcss-preset-env because in those cases the plugin will be executed when postcss-preset-env finished all the CSS processing.

For example, let's assume that for the next example, PostCSS RTLCSS is executed together with postcss-preset-env.

input

1.test {
2    color: red;
3    border-inline-start-width: thick;
4    margin-inline-end: 5px;
5    padding-inline-start: 20px;
6}

runOnExit in false (default)

1const options = {
2    runOnExit: false // This is the default value
3};

output

1.test {
2    color: red;
3    border-inline-start-width: thick;
4    margin-inline-end: 5px;
5    padding-inline-start: 20px;
6}

PostCSS RTLCSS didn't apply any change because it was executed at the beginning and it doesn't support CSS logical properties.

runOnExit in true

1const options = {
2    runOnExit: true
3};

output

1.test {
2    color: red;
3}
4
5[dir="ltr"] .test {
6    border-left-width: thick;
7    margin-right: 5px;
8    padding-left: 20px;
9}
10
11[dir="rtl"] .test {
12    border-right-width: thick;
13    margin-left: 5px;
14    padding-right: 20px;
15}

postcss-preset-env executed postcss-logical behind the scenes in the CSS and converted its properties from logical to physical. After it finishes, PostCSS RTLCSS is executed and it makes the necessary changes to add the LTR and RTL prefixes.

---

Control Directives

Control directives are placed between rules or declarations. They can target a single node or a set of nodes.

[!IMPORTANT] Block directives (the ones that start with begin and end with end) should be placed outside rules to apply the directive to multiple rules or inside a rule to apply the directive to multiple declarations. You should not place the begin of a directive outside a rule and the end inside one (or vice versa) or you will get undesired results.

Directive	Description
/*rtl:ignore*/	Ignores processing of the following rule or declaration
/*rtl:begin:ignore*/	Starts an ignoring block
/*rtl:end:ignore*/	Ends an ignoring block
/*rtl:freeze*/	Freezes the rule or declaration in the current direction but does nothing with the counterpart direction if there are flippable declarations
/*rtl:begin:freeze*/	Starts a freeze block
/*rtl:end:freeze*/	Ends a freeze block
/*rtl:urls*/	This directive set the processUrls option to true in the next declaration or in the declarations of the next rule no mattering the value of the global processUrls option
/*rtl:begin:urls*/	Starts a processUrls block block
/*rtl:end:urls*/	Ends a processUrls block block
/*rtl:rules*/	This directive set the processRuleNames option to true in the next rule no mattering the value of the global processRuleNames option
/*rtl:begin:rules*/	Starts a processRuleNames block block
/*rtl:end:rules*/	Ends a processRuleNames block block
/*rtl:source:{source}*/	Set the source of a rule or a declaration no mattering the value of the source property
/*rtl:begin:source:{source}*/	Starts a source block
/*rtl:end:source*/	Ends a source block
/*rtl:raw:{CSS}*/	Parses the CSS parameter and inserts it in its place. Depending on the source parameter the parsed CSS will be treated as rtl or ltr

---

/*rtl:ignore*/

This directive ignores processing of the following rule or declaration. In the next block the whole declaration will be ignored.

input

1/*rtl:ignore*/
2.test1, .test2 {
3    text-align: left;
4    left: 10px;
5}

output

1.test1, .test2 {
2    text-align: left;
3    left: 10px;
4}

In the next block only the left property will be ignored:

input

1.test3, .test4 {
2    text-align: left;
3    /*rtl:ignore*/
4    left: 10px;
5}

output

1.test3, .test4 {
2    left: 10px;
3}
4
5[dir="ltr"] .test3, [dir="ltr"] .test4 {
6    text-align: left;
7}
8
9[dir="rtl"] .test3, [dir="rtl"] .test4 {
10    text-align: right;
11}

---

/*rtl:begin:ignore*/ and /*rtl:end:ignore*/

These directives should be used together, they will provide the beginning and the end for ignoring rules or declarations.

[!NOTE] The directives inserted between these blocks will be ignored and maintained in the final output.

Ignoring multiple rules:

input

1/*rtl:begin:ignore*/
2.test1, .test2 {
3    left: 10px;
4    text-align: left;
5}
6
7.test3 {
8    padding: 1px 2px 3px 4px;
9}
10/*rtl:end:ignore*/

output

1.test1, .test2 {
2    left: 10px;
3    text-align: left;
4}
5
6.test3 {
7    padding: 1px 2px 3px 4px;
8}

Ignoring multiple declarations:

input

1.test1, .test2 {
2    left: 10px;
3    /*rtl:begin:ignore*/
4    margin-left: 4em;
5    padding: 1px 2px 3px 4px;
6    /*rtl:end:ignore*/
7    text-align: left;
8}

output

1.test1, .test2 {
2    margin-left: 4em;
3    padding: 1px 2px 3px 4px;
4}
5
6[dir="ltr"] .test1, [dir="ltr"] .test2 {
7    left: 10px;
8    text-align: left;
9}
10
11[dir="rtl"] .test1, [dir="rtl"] .test2 {
12    right: 10px;
13    text-align: right;
14}

---

/*rtl:freeze*/

[!IMPORTANT] This directive only works in combined mode. If you use it in override or diff modes it will be ignored.

This directive freezes the rule or declaration in the current direction but does nothing with the counterpart direction. When used with a rule, it will freeze it in the current direction even if it is doesn't contain flippable declarations. When it is used in a declration, it will freeze the declaration in the current direction even if it is not flippable.

input

1/*rtl:freeze*/
2.test1, .test2 {
3    color: red;
4    text-align: left;
5    left: 10px;
6}
7
8.test3 {
9    /*rtl:freeze*/
10    text-align: center;
11    /*rtl:freeze*/
12    padding: 10px 20px 30px 40px;
13    margin: 1px 2px 3px 4px;
14}

output

1[dir="ltr"] .test1, [dir="ltr"] .test2 {
2    color: red;
3    text-align: left;
4    left: 10px;
5}
6
7[dir="ltr"] .test3 {
8    text-align: center;
9    padding: 10px 40px 30px 20px;
10    margin: 1px 4px 3px 2px;
11}
12
13[dir="rtl"] .test3 {
14    margin: 1px 4px 3px 2px;
15}

---

/*rtl:begin:freeze*/ and /*rtl:end:freeze*/

[!IMPORTANT] This directive only works in combined mode. If you use it in override or diff modes it will be ignored.

These directives should be used together, they will provide the beginning and the end for freezing rules or declarations. The rules or declarations between these blocks, will be frozen in the current direction even if there are no flippable declarations involved.

Freezing multiple rules:

input

1/*rtl:begin:freeze*/
2.test1, .test2 {
3    color: #FFF;
4    left: 10px;
5    text-align: left;
6}
7
8.test3 {
9    padding: 1px 2px 3px 4px;
10}
11/*rtl:end:freeze*/

output

1[dir="ltr"] .test1, [dir="ltr"] .test2 {
2    color: #FFF;
3    left: 10px;
4    text-align: left;
5}
6
7[dir="ltr"] .test3 {
8    padding: 1px 2px 3px 4px;
9}

Freezing multiple declarations:

input

1.test1, .test2 {
2    color: red;
3    left: 10px;
4    /*rtl:begin:freeze*/
5    margin-left: 4em;
6    padding: 1px 2px 3px 4px;
7    /*rtl:end:freeze*/
8    text-align: left;
9}

output

1.test1, .test2 {
2    color: red;
3}
4
5[dir="ltr"] .test1, [dir="ltr"] .test2 {
6    left: 10px;
7    margin-left: 4em;
8    padding: 1px 2px 3px 4px;
9    text-align: left;
10}
11
12[dir="rtl"] .test1, [dir="rtl"] .test2 {
13    right: 10px;
14    text-align: right;
15}

---

/*rtl:urls*/

This directive set the processUrls option to true in the next declaration or in the declarations of the next rule no mattering the value of the global processUrls option:

input

1/*rtl:urls*/
2.test1 {
3    background-image: url("/buttons/button-ltr.png");
4}
5
6.test2 {
7    /*rtl:urls*/
8    background-image: url("/icons/icon-left.png");
9}

output

1[dir="ltr"] .test1 {
2    background-image: url("/buttons/button-ltr.png");
3}
4
5[dir="rtl"] .test1 {
6    background-image: url("/buttons/button-rtl.png");
7}
8
9[dir="ltr"] .test2 {
10    background-image: url("/icons/icon-left.png");
11}
12
13[dir="rtl"] .test2 {
14    background-image: url("/icons/icon-right.png");
15}

---

/*rtl:begin:urls*/ and /*rtl:end:urls*/

These directives should be used together, they will provide the beginning and the end for processUrls blocks.

input

1/*rtl:begin:urls*/
2.test1 {
3    background-image: url("/buttons/button-ltr.png");
4}
5
6.test2 {
7    background-image: url("/icons/icon-left.png");
8}
9/*rtl:end:urls*/
10
11.test3 {
12    /*rtl:begin:urls*/
13    background-image: url("/images/background-left.png");
14    cursor: url("/images/cursor-ltr.png");
15    /*rtl:end:urls*/
16}

output

1[dir="ltr"] .test1 {
2    background-image: url("/buttons/button-ltr.png");
3}
4
5[dir="rtl"] .test1 {
6    background-image: url("/buttons/button-rtl.png");
7}
8
9[dir="ltr"] .test2 {
10    background-image: url("/icons/icon-left.png");
11}
12
13[dir="rtl"] .test2 {
14    background-image: url("/icons/icon-right.png");
15}
16
17[dir="ltr"] .test3 {
18    background-image: url("/images/background-left.png");
19    cursor: url("/images/cursor-ltr.png");
20}
21
22[dir="rtl"] .test3 {
23    background-image: url("/images/background-right.png");
24    cursor: url("/images/cursor-rtl.png");
25}

---

/*rtl:rules*/

This directive set the processRuleNames option to true in the next rule no mattering the value of the global processRuleNames option:

input

1/*rtl:rules*/
2.test1-ltr {
3    background-image: url('/images/test1-l.png');
4}
5
6/*rtl:rules*/
7.test1-rtl {
8    background-image: url('/images/test1-r.png');
9}
10
11/*rtl:rules*/
12.test2-left::before {
13    content: "\f007";
14}
15
16.test2-right::before {
17    content: "\f010";
18}

output

1[dir="ltr"] .test1-ltr {
2    background-image: url('/images/test1-l.png');
3}
4
5[dir="rtl"] .test1-ltr {
6    background-image: url('/images/test1-r.png');
7}
8
9[dir="ltr"] .test1-rtl {
10    background-image: url('/images/test1-r.png');
11}
12
13[dir="rtl"] .test1-rtl {
14    background-image: url('/images/test1-l.png');
15}
16
17/* These selectors will not be processed because only one of them has the rtl:rules directive */
18.test2-left::before {
19    content: "\f007";
20}
21
22.test2-right::before {
23    content: "\f010";
24}

---

/*rtl:begin:rules*/ and /*rtl:end:rules*/

These directives should be used together, they will provide the beginning and the end for processRuleNames blocks.

input

1.test1-ltr {
2    background-image: url('/images/test1-l.png');
3}
4
5.test1-rtl {
6    background-image: url('/images/test1-r.png');
7}
8
9/*rtl:begin:rules*/
10.test2-left::before {
11    content: "\f007";
12}
13
14.test2-right::before {
15    content: "\f010";
16}
17/*rtl:begin:rules*/

output

1.test1-ltr {
2    background-image: url('/images/test1-l.png');
3}
4
5.test1-rtl {
6    background-image: url('/images/test1-r.png');
7}
8
9[dir="ltr"] .test2-left::before {
10    content: "\f007";
11}
12
13[dir="rtl"] .test2-left::before {
14    content: "\f010";
15}
16
17[dir="ltr"] .test2-right::before {
18    content: "\f010";
19}
20
21[dir="rtl"] .test2-right::before {
22    content: "\f007";
23}

---

/*rtl:source:{source}*/

This directive sets the source of a rule or a directive ignoring the value of the source property:

input

1/*rtl:source:rtl*/
2.test {
3    color: #FFF;
4    border-left: 1px solid #666;
5    padding: 10px 5px 10px 20px;
6    text-align: left;
7    width: 100%;
8}

output

1.test {
2    color: #FFF;
3    width: 100%;
4}
5
6[dir="ltr"] .test {
7    border-right: 1px solid #666;
8    padding: 10px 20px 10px 5px;
9    text-align: right;
10}
11
12[dir="rtl"] .test {
13    border-left: 1px solid #666;
14    padding: 10px 5px 10px 20px;
15    text-align: left;
16}

---

/*rtl:begin:source:{source}*/ and /*rtl:end:{source}*/

These directives should be used together, they will provide the beginning and the end of source blocks for rules or declarations:

input

1.test {
2    color: #FFF;
3    border-left: 1px solid #666;
4    /*rtl:begin:source:rtl*/
5    padding: 10px 5px 10px 20px;
6    text-align: left;
7    /*rtl:end:source*/
8    width: 100%;
9}

output

1.test {
2    color: #FFF;
3    width: 100%;
4}
5
6[dir="ltr"] .test {
7    border-left: 1px solid #666;
8    padding: 10px 20px 10px 5px;
9    text-align: right;
10}
11
12[dir="rtl"] .test {
13    border-right: 1px solid #666;
14    padding: 10px 5px 10px 20px;
15    text-align: left;
16}

---

/*rtl:raw:{CSS}*/

Parses the CSS parameter and inserts it in its place. Depending on the source parameter the parsed CSS will be treated as rtl or ltr:

input

1.test1 {
2    color: #EFEFEF;
3    left: 10px;
4    /*rtl:raw:
5    height: 50px;
6    width: 100px;*/
7}
8
9/*rtl:raw:.test2 {
10    color: #EFEFEF;
11    left: 10px;
12    width: 100%;    
13}
14
15.test3 {
16    transform: translate(10px, 20px);
17}
18*/

output

1.test1 {
2    color: #EFEFEF;
3}
4
5[dir="ltr"] .test1 {
6    left: 10px;
7}
8
9[dir="rtl"] .test1 {
10    right: 10px;
11    height: 50px;
12    width: 100px;
13}
14
15[dir="rtl"] .test2 {
16    color: #EFEFEF;
17    left: 10px;
18    width: 100%;    
19}
20
21[dir="rtl"] .test3 {
22    transform: translate(10px, 20px);
23}

---

Value Directives

Value directives are placed anywhere inside the declaration value. They target the containing declaration node.

Directive	Description
/*rtl:ignore*/	Ignores processing of the declaration
/*rtl:append{value}*/	Appends {value} to the end of the declaration value
/*rtl:insert:{value}*/	Inserts {value} to where the directive is located inside the declaration value
/*rtl:prepend:{value}*/	Prepends {value} to the begining of the declaration value
/*rtl:{value}*/	Replaces the declaration value with {value}

---

/*rtl:ignore*/

This directive ignores processing of the current declaration:

input

1.test1, .test2 {
2    text-align: left /*rtl:ignore*/;
3    left: 10px;
4}

output

1.test1, .test2 {
2    text-align: left;
3}
4
5[dir="ltr"] .test1, [dir="ltr"] .test2 {
6    left: 10px;
7}
8
9[dir="rtl"] .test1, [dir="rtl"] .test2 {
10    right: 10px;
11}

---

/*rtl:append{value}*/

This directive appends {value} to the end of the declaration value:

input

1.test1, .test2 {
2    padding: 10px /*rtl:append20px*/;
3    left: 10px;
4}

output

1[dir="ltr"] .test1, [dir="ltr"] .test2 {
2    padding: 10px;
3    left: 10px;
4}
5
6[dir="rtl"] .test1, [dir="rtl"] .test2 {
7    padding: 10px 20px;
8    right: 10px;
9}

---

/*rtl:insert:{value}*/

This directive inserts {value} to where the directive is located inside the declaration value:

input

1.test1, .test2 {
2    padding: 10px/*rtl:insert 20px*/ 5px;
3    left: 10px;
4}

output

1[dir="ltr"] .test1, [dir="ltr"] .test2 {
2    padding: 10px 5px;
3    left: 10px;
4}
5
6[dir="rtl"] .test1, [dir="rtl"] .test2 {
7    padding: 10px 20px 5px;
8    right: 10px;
9}

---

/*rtl:prepend:{value}*/

This directive prepends {value} to the begining of the declaration value:

input

1.test1, .test2 {
2    font-family: Arial, Helvetica/*rtl:prepend:"Droid Arabic Kufi", */;
3    left: 10px;
4}

output

1[dir="ltr"] .test1, [dir="ltr"] .test2 {
2    font-family: Arial, Helvetica;
3    left: 10px;
4}
5
6[dir="rtl"] .test1, [dir="rtl"] .test2 {
7    font-family: "Droid Arabic Kufi", Arial, Helvetica;
8    right: 10px;
9}

---

/*rtl:{value}*/

This directive replaces the declaration value with {value}:

input

1.test1, .test2 {
2    font-family: Arial, Helvetica/*rtl:"Droid Arabic Kufi"*/;
3    left: 10px;
4}

output

1[dir="ltr"] .test1, [dir="ltr"] .test2 {
2    font-family: Arial, Helvetica;
3    left: 10px;
4}
5
6[dir="rtl"] .test1, [dir="rtl"] .test2 {
7    font-family: "Droid Arabic Kufi";
8    right: 10px;
9}

---

If you do not use PostCSS, add it according to official docs and set this plugin in settings.