Showcase logo

Right-to-Left (RTL) support

Right-to-Left (RTL) is a text direction used by languages such as Arabic, Hebrew, Persian, and Urdu. The Blok design system provides automatic RTL support based on the user's browser language preference. When an RTL language is detected, the entire UI layout flips horizontally — sidebars move to the opposite side, text aligns to the right, and navigation elements flip direction. Code blocks always remain LTR for readability.

The following languages are automatically detected as RTL.

  • Arabicar
  • Hebrewhe
  • Persian/Farsifa
  • Urduur
  • Yiddishyi
  • Yiddish (alternative)ji
  • Kurdishku
  • Pashtops
  • Sindhisd

Note: any language not in this list defaults to LTR (Left-to-Right).

Install the required dependency from your command line.

npm install @radix-ui/react-direction

Create utility functions for detecting RTL languages and getting the browser language.

// List of RTL language codes
const RTL_LANGUAGES = [
  "ar", // Arabic
  "he", // Hebrew
  "fa", // Persian/Farsi
  "ur", // Urdu
  "yi", // Yiddish
  "ji", // Yiddish (alternative)
  "ku", // Kurdish
  "ps", // Pashto
  "sd", // Sindhi
] as const;

// Determines if a language code is RTL
export function isRTL(language: string): boolean {
  const langCode = language.toLowerCase().split("-")[0];
  return RTL_LANGUAGES.includes(langCode as typeof RTL_LANGUAGES[number]);
}

// Gets the direction based on language code
export function getDirectionFromLanguage(language: string): "ltr" | "rtl" {
  return isRTL(language) ? "rtl" : "ltr";
}

// Gets the browser's preferred language
export function getBrowserLanguage(): string {
  if (typeof window === "undefined") return "en";
  const languages = navigator.languages || [navigator.language];
  return languages[0] || "en";
}

The DirectionProvider wraps your app to provide global reading direction. It enables all Radix UI primitives to inherit the global reading direction.

API reference

PropTypeDefault
dir"ltr" | "rtl"No default value

To implement RTL support in your application, wrap your app with the DirectionProvider component.

"use client";

import { useDirectionState } from "@/hooks/registry/use-direction";
import { DirectionProvider as RadixDirectionProvider } from "@radix-ui/react-direction";

export function DirectionProvider({ children }: { children: React.ReactNode }) {
  const dir = useDirectionState();
  return <RadixDirectionProvider dir={dir}>{children}</RadixDirectionProvider>;
}

The provider automatically detects the browser language and sets the appropriate direction. You can also use the useDirection() hook in your components to access the current direction.

import { useDirection } from "@/hooks/registry/use-direction";

export function MyComponent() {
  const direction = useDirection();

  return (
    <div className={direction === "rtl" ? "text-right" : "text-left"}>
      Content
    </div>
  );
}
  1. Install the dependency (see Installation section above).
  2. Create direction utilities (optional, for automatic detection) — a utility file to detect RTL languages and get the browser language. See src/lib/utils/direction.ts for reference.
  3. Wrap your app with DirectionProvider in your root layout (see Implementation section above).
  4. Use the useDirection hook in components that need to adapt to RTL.

Basic usage

import { DirectionProvider as RadixDirectionProvider } from "@radix-ui/react-direction";

export default function App() {
  return (
    <RadixDirectionProvider dir="rtl">
      {/* Your app content */}
    </RadixDirectionProvider>
  );
}

Using the hook in components

import { useDirection } from "@/hooks/registry/use-direction";
import { cn } from "@/lib/utils/cn";

export function Sidebar() {
  const direction = useDirection();

  return (
    <aside className={cn(
      "fixed top-0 h-full",
      direction === "rtl" ? "right-0" : "left-0"
    )}>
      {/* Sidebar content */}
    </aside>
  );
}

Keeping code blocks LTR

Code blocks should always remain LTR for readability.

export function CodeBlock({ code }: { code: string }) {
  return (
    <div dir="ltr">
      <pre className="overflow-x-auto p-4">
        <code>{code}</code>
      </pre>
    </div>
  );
}