Skip to main content

RTL / i18n Support

The library is built Arabic-first. Every component uses logical CSS properties and all MUI component overrides respect the active text direction.

How direction works​

  1. LanguageProvider detects the current language (from controlled prop, localStorage, or browser setting).
  2. It swaps the Emotion CacheProvider between a "mui" (LTR) cache and a "muirtl" (RTL) cache that includes stylis-plugin-rtl.
  3. MUI automatically generates mirrored CSS (padding-inline-start, border-inline-end, etc.) for all MUI components.
  4. It sets document.dir and document.documentElement.lang to keep native HTML directionality in sync.

Component authoring rules​

When writing components for the library, follow these rules:

Use logical CSS properties​

// ✅ Correct — works in both directions
sx={{ paddingInlineStart: 2, marginInlineEnd: 1 }}

// ❌ Wrong — breaks in RTL
sx={{ paddingLeft: 2, marginRight: 1 }}

MUI components are automatically handled​

MUI's sx prop and component overrides in ThemeContext use logical properties throughout. Do not override with physical properties.

Integrating with i18next​

import i18n from "i18next";
import { initReactI18next } from "react-i18next";

i18n.use(initReactI18next).init({
  /* config */
});

// In your app root:
<AppProvider language={i18n.language} onLanguageChange={(lang) => i18n.changeLanguage(lang)}>
  <App />
</AppProvider>;

LanguageProvider listens to storage events on "language" and "i18nextLng" keys, so changing the language via i18next automatically updates the direction even without passing language as a controlled prop.

Arabic fonts​

Import @xocialive/ui-components/style.css to get Tajawal, Cairo, IBM Plex Sans Arabic, and Playpen Sans Arabic. These load from Google Fonts CDN. See Fonts Setup.

Testing RTL​

The library's Storybook uses a direction toolbar toggle. You can switch between LTR and RTL without changing your browser language:

📖 Open Storybook