Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

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

wants to merge 8 commits into from

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 like margin-*, padding-*, border-*, inset and text-align.

Only properties that directly handled by rtlcss.

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

The compiled CSS includes both LTR and RTL styles, as follows:

/* ❌ 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
}

By migrating to native CSS solution, the compiled CSS is as follows:

/* ✅ 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%. The performance improvement decreases "Unused CSS". You can see the "Coverage" panel in you Dev Tools to verify to results.

@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 

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

commit: 88a913b

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