Skip to content

feat(theme): use native CSS for RTL instead of using rtlcss package#5034

Open
rami-elementor wants to merge 17 commits intovuejs:mainfrom
rami-elementor:rtl
Open

feat(theme): use native CSS for RTL instead of using rtlcss package#5034
rami-elementor wants to merge 17 commits intovuejs:mainfrom
rami-elementor:rtl

Conversation

@rami-elementor
Copy link

@rami-elementor rami-elementor commented Nov 18, 2025 •
edited
Loading

Description

Currently, VitePress is using rtlcss package to manage styles based on writing-direction. It creates two sets of styles, for LTR and RTL styles, one for each direction. This is not necessary, with some adjustments we can support styling for both writing direction, natively.

The simplest example for native RTL support is the text align:

/* ❌ Before */

.text {
  text-align: left; /* LTR */
}

[dir="rtl"] .text {
  text-align: right; /* RTL */
}
/* ✅ After */

.text {
  text-align: start; /* LTR & RTL */
}

With direction‐relative equivalents like start/end instead of left/right, we reduce the difference between LTR and RTL view. The browser decides how to align the text based on the writing direction.

The end goal is to stop using the rtlcss package. It will not only delegate the page direction management to the browser, but also improve frontend performance, optimize the CI/CD by removing uneasy steps, and reducing build time.

PR Fucos

This PR focuses only in RTL support, which is a subset of the Logical Properties. It's not a full migration to logical properties.

The focus is on properties that directly handled by rtlcss, like margin-*, padding-*, border-*, inset and text-align. It doesn't change width, height and other properties which are not related to RTL.

Additional Context

We use CSS logical properties and values to handle direction, but not all CSS properties have logical equivalents. In these cases we use the --vp-direction-multiplier to help with the writing direction.

:root {
  --vp-direction-multiplier: 1; /* 1 for LTR, -1 for RTL */
}

[dir="rtl"] {
  --vp-direction-multiplier: -1;
}

This helps rotate or translate on the X-axis to the correct directions based on the writing language.

transform: rotate(calc(45deg * var(--vp-direction-multiplier)));

The element will be rotated by 45deg in LTR, and -45deg in RTL.

Testing

I recommend using the "RTL toggle" chrome extension to track issues. It simply changes the dir="ltr|rtl" attribute on the <html> element.

Performance

Currently, the compiled CSS includes both LTR and RTL styles:

/* ❌ Before */

.vp-doc th {
    color: var(--vp-c-text-2);
    background-color: var(--vp-c-bg-soft);
    font-size: 14px;
    font-weight: 600
}

:where([dir=ltr]) .vp-doc th {
    text-align: left
}

:where([dir=rtl]) .vp-doc th {
    text-align: right
}

After migrating to native CSS, the compiled CSS is much smaller:

/* ✅ After */

.vp-doc th {
    text-align: start;
    color: var(--vp-c-text-2);
    background-color: var(--vp-c-bg-soft);
    font-size: 14px;
    font-weight: 600
}

This change reduces the CSS file size by 4%. It also decreases "Unused CSS", You can see the "Coverage" panel in your Dev Tools to verify the results. Overall, it improves performance for both LTR and RTL users.

Docs Update

The docs mention some specificity issues:

RTL Support (Experimental)

For RTL support, specify dir: 'rtl' in config and use some RTLCSS PostCSS plugin like https://github.com/MohammadYounes/rtlcss, https://github.com/vkalinichev/postcss-rtl or https://github.com/elchininet/postcss-rtlcss. You'll need to configure your PostCSS plugin to use :where([dir="ltr"]) and :where([dir="rtl"]) as prefixes to prevent CSS specificity issues.

When we fully migrate away from automated rtlcss, this paragraph can be removed from the docs.

@brc-dd brc-dd added theme Related to the theme cr-tracked labels Nov 18, 2025
@rami-elementor rami-elementor marked this pull request as ready for review November 19, 2025 09:13
@pkg-pr-new
Copy link

pkg-pr-new bot commented Nov 20, 2025 •
edited
Loading 

npm i https://pkg.pr.new/vitepress@5034

commit: c22966f

@rami-elementor rami-elementor mentioned this pull request Jan 5, 2026
Open
@brc-dd brc-dd force-pushed the main branch 3 times, most recently from 15a0278 to 09af6c7 Compare March 26, 2026 04:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

cr-tracked theme Related to the theme

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@rami-elementor @brc-dd