Skip to content
Tutorials Center
My learning

Topics

Lesson 45 of 58 ยท Customizing

RTL Support in Bootstrap

Support Arabic and Hebrew with Bootstrap 5.3: dir and lang, the RTL stylesheet, start and end utilities, RTLCSS and logical CSS for your own code.

Not every language runs from left to right. Arabic, Hebrew, Persian and Urdu are written right to left (RTL), and hundreds of millions of people read them every day. For these readers a good interface is not just translated: it is mirrored. The sidebar moves to the right, the back arrow points right, text aligns to the right edge and progress bars fill toward the left.

Bootstrap 5 was designed with this in mind. Its class names speak in terms of start and end instead of left and right, and it ships a ready-made right-to-left stylesheet. This lesson explains how to switch a page to RTL, what Bootstrap flips automatically, what you must handle yourself and how to write your own CSS so it works in both directions.

Why "start" and "end"?

In Bootstrap 5 the margin, padding, text, float and border utilities use logical names:

Old (Bootstrap 4) Bootstrap 5 Left-to-right Right-to-left
ml-3, mr-3 ms-3, me-3 left, right right, left
pl-3, pr-3 ps-3, pe-3 left, right right, left
text-left, text-right text-start, text-end left, right right, left
float-left, float-right float-start, float-end left, right right, left
border-left border-start left right
rounded-left rounded-start left corners right corners

(The old names are listed in Migrating from Bootstrap 4 and Using Icons.) If you use the start and end classes consistently, your layout is already prepared for RTL: the same HTML works in both directions. The grid also follows reading direction: in RTL, the first column is on the right.

Step 1: tell the browser the language and direction

Direction starts with HTML, not with Bootstrap. Two attributes on <html>:

HTML
<html lang="ar" dir="rtl">
  • lang tells browsers, screen readers and search engines the language.
  • dir="rtl" sets the base text direction. Text, inline layout, text-align: start, scrollbars and flex row order all follow it.

With dir alone, a Bootstrap page already flips a lot: flex rows, the grid order and start/end utilities. What it does not flip are details written with physical properties inside the compiled CSS, for example the position of a dropdown caret or the padding of a form select arrow. That is what the RTL stylesheet is for.

Step 2: load the RTL stylesheet

Bootstrap publishes a second CSS build, bootstrap.rtl.css, produced by running the normal CSS through a tool called RTLCSS. It swaps left for right, mirrors padding and margins, flips shadows and background positions, and so on. Load it instead of the regular stylesheet, never together with it:

HTML
<html lang="ar" dir="rtl">
<head>
  <link rel="stylesheet"
        href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.rtl.min.css">
</head>

The JavaScript bundle is the same for both directions.

You can try this without knowing a word of Arabic. The demo below renders the same layout with the regular and the RTL stylesheet, switching with a button. The Arabic sample text means "Welcome" and "Next".

Switch between LTR and RTL

Press the button and compare. The badge, back button, thick border, rounded corners, column order, progress bar and input group all mirror, with no change to the HTML classes. The demo switches the stylesheet with JavaScript to show both builds. In a real site you would normally choose one, based on the page's language, on the server.

What flips by itself and what does not

Handled for you by dir and the RTL stylesheet

  • Grid column order, flex row order and start/end utilities.
  • Margins, padding, borders, floats and text alignment in components.
  • Component internals: dropdown placement (dropdown-menu-start/end), carousel direction, breadcrumb separators, list-group borders, modal close buttons, form-select arrows, switches, input groups.

Your responsibility

  • Icons and images that imply direction: arrows, chevrons, "back" and "forward" glyphs, progress indicators, quotation marks and illustrations with a clear reading direction. Mirror them with a CSS transform in RTL:
CSS
[dir="rtl"] .icon-directional { transform: scaleX(-1); }

Do not mirror logos, photos, clocks, play buttons, checkmarks or numbers: they do not change in RTL.

  • Your own CSS written with left, right, margin-left, padding-right, text-align: left or border-left. Rewrite those with logical properties (below).
  • Text content: translated text, with correct punctuation, numerals and mixed-direction strings.
  • Fonts: Arabic and Hebrew need fonts with the right glyphs, and generally a slightly larger size and line height than Latin text.

Writing your own CSS for both directions

Replace physical properties with logical properties, which follow the writing direction:

Physical Logical
margin-left / margin-right margin-inline-start / margin-inline-end
padding-left / padding-right padding-inline-start / padding-inline-end
border-left border-inline-start
left / right inset-inline-start / inset-inline-end
text-align: left text-align: start
float: left float: inline-start
width / height inline-size / block-size (in horizontal text)
CSS
.notice {
  padding-inline: 1rem 1.5rem;          /* start, end */
  border-inline-start: 4px solid var(--bs-primary);
  margin-inline-end: auto;
}

Logical properties have strong browser support and make RTL support almost free. See Writing Modes for the full picture. Use [dir="rtl"] selectors only for what logical properties cannot express, such as flipping an icon.

Mixing directions: the dir attribute on elements

You can set dir on any element, not just <html>. A line of English in an Arabic page, a phone number or a code snippet can carry its own direction:

HTML
<p>ุงุณู… ุงู„ู…ุณุชุฎุฏู…: <span dir="ltr">[email protected]</span></p>
<code dir="ltr">npm install bootstrap</code>

For user-generated text where you do not know the direction, use dir="auto" so the browser picks it from the first strong character (a good habit for comments, chat messages and form inputs). Bootstrap's form-control works with dir="auto" as well. <bdi> isolates a fragment (like a username) so its direction cannot disturb the text around it.

Using Sass: generating RTL CSS yourself

If you compile Bootstrap from Sass (see Customizing with Sass), you can produce your own RTL build with the RTLCSS tool, the same one Bootstrap uses. Run it as a PostCSS step on the compiled CSS:

Terminal
npm install rtlcss
npx rtlcss dist/css/theme.css dist/css/theme.rtl.css

RTLCSS reads the CSS, swaps physical sides and writes a mirrored file. You can control its behavior with comment directives inside your Sass, for example /*rtl:ignore*/ to leave one declaration alone, or /*rtl:raw: ... */ to insert RTL-only CSS:

CSS
.hero {
  background-position: left top;           /*rtl:ignore*/
}
.brand {
  /*rtl:begin:ignore*/
  letter-spacing: 0.1em;
  /*rtl:end:ignore*/
}

Serve the normal file to LTR pages and the .rtl file to RTL pages. Because the two builds have the same class names, templates do not change.

A practical checklist

  1. Set lang and dir on <html> from the user's locale.
  2. Load bootstrap.rtl.min.css for RTL locales (the normal file otherwise).
  3. Use ms-, me-, ps-, pe-, text-start, float-end and friends, never left and right equivalents.
  4. Write custom CSS with logical properties.
  5. Mirror directional icons; leave logos and photos alone.
  6. Test with real RTL text, long strings and numerals. Check dropdowns, tooltips, carousels, modals and forms.
  7. Use dir="auto" or <bdi> for mixed or user-generated content.
  8. Test with a screen reader in an RTL language if you can, or ask a native reader to review.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does Bootstrap 5 use class names like ms-3 and text-end?

    Start and end flip with the writing direction, which makes the same markup reusable for both directions.
  2. 2. How should you load the RTL stylesheet?

    The RTL file is a complete mirrored build. Loading both would give conflicting rules.
  3. 3. Which of these should you mirror in RTL?

    Directional icons such as arrows and chevrons should flip. Logos, photos and media controls usually should not.
  4. 4. Which CSS is RTL-friendly?

    Logical properties follow the writing direction, while physical ones stay fixed and need separate RTL overrides.
  5. 5. What is dir="auto" useful for?

    dir=auto picks the direction from the first strong directional character, which suits comments, messages and inputs.

Summary

  • RTL support starts with lang and dir="rtl" on <html>, plus bootstrap.rtl.min.css instead of the regular stylesheet.
  • Bootstrap 5 uses start and end utilities, so the same HTML works in both directions.
  • You must mirror directional icons yourself, and write your own CSS with logical properties.
  • Use dir on single elements, dir="auto" for user content and <bdi> for isolated fragments.
  • With Sass builds, RTLCSS generates your own mirrored CSS; test with real RTL text and components.

Next lesson: Accessibility in Bootstrap, where you make your Bootstrap pages usable for everyone.