DEV Community

Cover image for RTL Is Not Just dir="rtl": What I Learned Shipping Vue Templates for the Arab Web
amine ben moussa
amine ben moussa

Posted on

RTL Is Not Just dir="rtl": What I Learned Shipping Vue Templates for the Arab Web

#vue #tailwindcss #i18n #a11y

I spent the last several months building Vue 3 templates with native RTL support. Along the way I learned that "RTL support" is one of the most overpromised, underdelivered claims in the frontend ecosystem.

Most templates that advertise Arabic or RTL support do roughly this:

[dir="rtl"] {
  direction: rtl;
}
Enter fullscreen mode Exit fullscreen mode

Ship it. Tweet it. Add a flag emoji to the README.

Then a real Arabic-speaking user opens the page and within 5 seconds notices the gradient flowing the wrong way, the chevron icon pointing into a wall, the date showing as 12/05/2024 when their entire region writes it as ٢٠٢٤/٠٥/١٢, and a card layout where the avatar floats off into nothingness because someone wrote margin-left: 16px six months ago and forgot.

This article is about what actually breaks, why a 2-line CSS rule cannot fix it, and the concrete patterns I now use in production with Vue 3 and Tailwind v4.

The Illusion: dir="rtl" Is Step Zero, Not the Solution

Setting dir="rtl" on the <html> tag does flip text direction. That is approximately 15% of the work.

The other 85% lives in things the browser cannot guess:

  • Directional icons: chevrons, arrows, "send" buttons, breadcrumb separators
  • Gradients with direction: linear-gradient(to right, ...) is now wrong
  • Transforms: translateX(-100%) slides the wrong way
  • Animations: a sidebar that slides in from the left is now coming out of the screen
  • Box shadows with offsets: box-shadow: 4px 0 ... casts the shadow in the wrong direction
  • Border radius on specific corners: border-top-left-radius is now visually wrong
  • Asymmetric layouts: anything with position: absolute; left: 0
  • Mixed-direction content: Arabic with embedded numbers, URLs, code, brand names None of these are fixed by dir="rtl". All of them are visible to a real user. And every single one of them is in your production code right now if you've never thought about it.

What Tailwind v4 Changes (Actually a Big Deal)

If you are still on Tailwind v3 and writing ml-4, pr-2, text-left, you are writing direction-dependent CSS. Every single one of those utilities has a logical equivalent that should be your default:

Direction-dependent Logical (use these)
ml-4 ms-4 (margin-start)
mr-4 me-4 (margin-end)
pl-2 ps-2
pr-2 pe-2
text-left text-start
text-right text-end
left-0 start-0
right-0 end-0
border-l border-s
rounded-tl-lg rounded-ss-lg

Tailwind v4 promotes these to first-class citizens with cleaner naming. The s is for start (left in LTR, right in RTL) and e is for end (right in LTR, left in RTL).

The migration cost is real but mechanical. A regex sweep gets you 80% of the way:

# In your editor: find and replace, with regex enabled
\bml-          →  ms-
\bmr-          →  me-
\bpl-          →  ps-
\bpr-          →  pe-
\btext-left    →  text-start
\btext-right   →  text-end
Enter fullscreen mode Exit fullscreen mode

Review the diff carefully. Some ml- should not become ms- (e.g., when the design genuinely requires "left" regardless of direction, like a dedicated LTR debug panel). But those cases are rare and identifiable.

Vue 3: Reactive Direction Without Page Reload

Switching language should never require a reload. Here's the minimum viable setup using vue-i18n plus a composable that exposes the direction:

// composables/useDirection.ts
import { computed } from 'vue'
import { useI18n } from 'vue-i18n'

const RTL_LOCALES = new Set(['ar', 'he', 'fa', 'ur'])

export function useDirection() {
  const { locale } = useI18n()

  const dir = computed(() =>
    RTL_LOCALES.has(locale.value) ? 'rtl' : 'ltr'
  )

  const isRTL = computed(() => dir.value === 'rtl')

  return { dir, isRTL, locale }
}
Enter fullscreen mode Exit fullscreen mode

Then in your root component (or a Nuxt plugin):

<script setup lang="ts">
import { watchEffect } from 'vue'
import { useDirection } from '~/composables/useDirection'

const { dir, locale } = useDirection()

watchEffect(() => {
  if (typeof document !== 'undefined') {
    document.documentElement.dir = dir.value
    document.documentElement.lang = locale.value
  }
})
</script>
Enter fullscreen mode Exit fullscreen mode

This is the entire infrastructure. The <html> tag updates reactively, Tailwind's logical utilities respond, and your components don't need to know about direction — they just use ms-* and pe-* and trust the cascade.

Directional Icons: The Pattern That Saves You

Icons that point in a direction (arrows, chevrons, send buttons, breadcrumb separators) need to flip in RTL. Doing this with conditional rendering is verbose. Doing it with CSS is cleaner:

<template>
  <button class="flex items-center gap-2">
    Continue
    <ChevronRightIcon class="h-4 w-4 rtl:rotate-180" />
  </button>
</template>
Enter fullscreen mode Exit fullscreen mode

Tailwind v4 ships RTL variants out of the box. rtl:rotate-180 applies only when dir="rtl" is in scope. Same for ltr: if you need to scope something to LTR only.

For SVG icons that come from a library, this works for most. For icons with internal asymmetric details (like a "user with arrow" combined glyph), you may need to swap the asset entirely. But for the 90% case of simple directional indicators, rtl:rotate-180 is the answer.

The Non-CSS Trap: Numbers, Dates, Currency

This is the section that separates real Arabic support from fake Arabic support.

Numerals

Arabic-speaking users in many regions read both Western numerals (123) and Arabic-Indic numerals (١٢٣). Some prefer one over the other depending on context. Hardcoding 123 in your dashboard charts will look correct to many users, but 2,500.50 SAR looks alien when displayed alongside Arabic text — the number reads in one direction, the currency code in another.

Use Intl.NumberFormat with locale awareness:

const formatCurrency = (value: number, locale: string, currency: string) =>
  new Intl.NumberFormat(locale, {
    style: 'currency',
    currency,
  }).format(value)

formatCurrency(2500.50, 'ar-SA', 'SAR')
// "٢٬٥٠٠٫٥٠ ر.س.‏"

formatCurrency(2500.50, 'en-US', 'USD')
// "$2,500.50"
Enter fullscreen mode Exit fullscreen mode

The browser knows where the currency symbol goes, which separators to use, and which numeral system fits the locale. Don't reinvent this.

Dates

Same story. Intl.DateTimeFormat handles the entire Arabic, Persian, Hebrew, Hindi calendar landscape:

new Intl.DateTimeFormat('ar-SA', { dateStyle: 'long' }).format(new Date())
// "٢٠ ربيع الآخر ١٤٤٧ هـ"  (Hijri calendar, used in Saudi Arabia)

new Intl.DateTimeFormat('ar-EG', { dateStyle: 'long' }).format(new Date())
// "٦ نوفمبر ٢٠٢٥"  (Gregorian calendar, but Arabic numerals + Arabic month names)
Enter fullscreen mode Exit fullscreen mode

Yes, the same Arabic-speaking user in Riyadh and Cairo on the same day will see two different dates, because they use different calendars by default. Hardcoding format: 'DD/MM/YYYY' is a tell to your users that you didn't think about them.

Currency placement

The Saudi Riyal symbol (ر.س) goes after the number in some contexts and before in others. The browser handles this. Stop fighting it.

Mixed-Direction Content (the BiDi Problem)

Arabic mixed with English, numbers, URLs, or code is where the Bidirectional Algorithm enters your life. By default, browsers handle this reasonably with the Unicode BiDi algorithm — but ambiguous cases break.

Example: a user-generated comment in Arabic that contains a phone number with a dash:

"اتصل بي على 555-1234 الآن"
Enter fullscreen mode Exit fullscreen mode

Without explicit BiDi marks, the dash and digits can render in unexpected order. Use Unicode Right-to-Left and Left-to-Right marks (\u200F and \u200E) or, in CSS, the unicode-bidi and direction properties on inline spans.

In practice, for the 95% case where you're rendering trusted content, browsers do this correctly. For user-generated content with embedded LTR sequences, test on actual devices with actual users.

A Migration Path That Works

If you have an existing Vue project that you want to make properly RTL-friendly, in this order:

  1. Audit your spacing utilities. Run that regex sweep from ml-/mr- to ms-/me-. Review the diff. Ship it.
  2. Audit your text alignment. text-left to text-start. Same routine.
  3. Audit your transforms and animations. Look for translateX, translate-x-*, slide-from-left keyframes. Add rtl: variants or rewrite using logical positioning.
  4. Audit your icons. Search for chevron, arrow, send, share icons. Add rtl:rotate-180 where direction matters semantically.
  5. Replace hardcoded date and number formatting. Move everything to Intl.NumberFormat and Intl.DateTimeFormat with locale awareness.
  6. Add a locale switcher and test the whole app at dir="rtl" with a real Arabic translation, not Lorem Ipsum. That last point matters. The Latin-script Lorem Ipsum used in development hides 90% of the issues that show up with actual Arabic glyphs, line height, and word breaking. Test with real translated content.

Closing: This Is Plumbing, Not Marketing

The reason most templates ship broken RTL is not malice or laziness — it's that the developers never spent a day using their own template in Arabic. If you have, you'll fix the issues. If you haven't, you'll keep shipping dir="rtl" and wondering why the Saudi market doesn't convert.

If you want a starting point that has already gone through this audit (Vue 3, Tailwind v4, 7 languages, real Arabic content tested by real Arabic speakers), I built QalamUI for exactly this reason. There's also a free live demo if you want to poke at the components.

But more than anything: the next time you read "RTL support" on a template page, ask the seller to send you a screenshot of the dashboard with dir="rtl" and Arabic content. The answer will tell you everything.

If this article saved you a debugging session, drop a comment with what you're building for the Arabic-speaking web. I'm collecting case studies of teams shipping in MENA and would love to learn from yours.

Top comments (0)