# RTL

Right-to-left support for WebJs UI components.

Source: https://webjs.dev/ui/docs/rtl

WebJs UI components have first-class support for right-to-left (RTL) layouts. Text alignment, positioning, and directional styles automatically adapt for languages like Arabic, Hebrew, and Persian.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
  cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass,
  cardActionClass, cardContentClass, cardFooterClass,
} from '#components/ui/card.ts';
import { inputClass } from '#components/ui/input.ts';
import { labelClass } from '#components/ui/label.ts';

const translations = {
  en: {
    dir: 'ltr',
    values: {
      title: 'Login to your account',
      description: 'Enter your email below to login to your account',
      signUp: 'Sign Up',
      email: 'Email',
      emailPlaceholder: 'm@example.com',
      password: 'Password',
      forgotPassword: 'Forgot your password?',
      login: 'Login',
      loginWithGoogle: 'Login with Google',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      title: 'تسجيل الدخول إلى حسابك',
      description: 'أدخل بريدك الإلكتروني أدناه لتسجيل الدخول إلى حسابك',
      signUp: 'إنشاء حساب',
      email: 'البريد الإلكتروني',
      emailPlaceholder: 'm@example.com',
      password: 'كلمة المرور',
      forgotPassword: 'نسيت كلمة المرور؟',
      login: 'تسجيل الدخول',
      loginWithGoogle: 'تسجيل الدخول باستخدام Google',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      title: 'התחבר לחשבון שלך',
      description: 'הזן את האימייל שלך למטה כדי להתחבר לחשבון שלך',
      signUp: 'הירשם',
      email: 'אימייל',
      emailPlaceholder: 'm@example.com',
      password: 'סיסמה',
      forgotPassword: 'שכחת את הסיסמה?',
      login: 'התחבר',
      loginWithGoogle: 'התחבר עם Google',
    },
  },
};

// The provider is the dir attribute: every part styles itself with logical
// properties, so dir="rtl" on the card flips the whole layout.
export default function CardRtl() {
  const lang = 'ar';
  const { dir, values: t } = translations[lang];

  return html`
    <div data-slot="card" data-size="default" dir=${dir} lang=${lang} class=${cn(cardClass(), 'w-full max-w-sm')}>
      <div data-slot="card-header" class=${cardHeaderClass()}>
        <div data-slot="card-title" class=${cardTitleClass()}>${t.title}</div>
        <div data-slot="card-description" class=${cardDescriptionClass()}>${t.description}</div>
        <div data-slot="card-action" class=${cardActionClass()}>
          <button type="button" data-slot="button" data-variant="link" data-size="default" class=${buttonClass({ variant: 'link' })}>${t.signUp}</button>
        </div>
      </div>
      <div data-slot="card-content" class=${cardContentClass()}>
        <form>
          <div class="flex flex-col gap-6">
            <div class="grid gap-2">
              <label data-slot="label" for="email-rtl" class=${labelClass()}>${t.email}</label>
              <input data-slot="input" id="email-rtl" type="email" placeholder=${t.emailPlaceholder} required class=${inputClass()}>
            </div>
            <div class="grid gap-2">
              <div class="flex items-center">
                <label data-slot="label" for="password-rtl" class=${labelClass()}>${t.password}</label>
                <a href="#" class="ms-auto inline-block text-sm underline-offset-4 hover:underline">${t.forgotPassword}</a>
              </div>
              <input data-slot="input" id="password-rtl" type="password" required class=${inputClass()}>
            </div>
          </div>
        </form>
      </div>
      <div data-slot="card-footer" class=${cn(cardFooterClass(), 'flex-col gap-2')}>
        <button type="submit" data-slot="button" data-variant="default" data-size="default" class=${cn(buttonClass(), 'w-full')}>${t.login}</button>
        <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${cn(buttonClass({ variant: 'outline' }), 'w-full')}>${t.loginWithGoogle}</button>
      </div>
    </div>
  `;
}
```

The components are written with logical properties, so they install ready for both directions. Set `dir="rtl"` on an element and every component inside it lays itself out from the right.

## Get Started

### Set the direction

Add the `dir="rtl"` and `lang="ar"` attributes to the `html` tag. Update `lang="ar"` to your target language. The root layout is the one layout that may write the document shell, so it is where the attributes go.

```ts title="app/layout.ts"
import { html } from '@webjsdev/core';
import type { LayoutProps } from '@webjsdev/core';

export default function RootLayout({ children }: LayoutProps) {
  return html`<!doctype html>
<html lang="ar" dir="rtl">
  <head></head>
  <body>${children}</body>
</html>`;
}
```

The `dir` attribute is the direction provider, and it works on any element, so one region of a left-to-right page can be right-to-left: `<section dir="rtl" lang="ar">`. Set `lang` beside it, since a screen reader picks its voice from `lang` while the layout comes from `dir`.

### Add Font

For the best RTL experience, we recommend using fonts that have proper support for your target language. [Noto](https://fonts.google.com/noto) is a great font family for this and it pairs well with Inter and Geist.

Self-host the font file under `public/fonts/`, declare it in the Tailwind entry your app compiles, and make it the sans family:

```css title="public/input.css"
@font-face {
  font-family: "Noto Sans Arabic";
  src: url("/fonts/noto-sans-arabic.woff2") format("woff2");
  font-weight: 100 900;
  font-display: swap;
}

@theme {
  --font-sans: "Noto Sans Arabic", ui-sans-serif, system-ui, sans-serif;
}
```

For other languages, eg. Hebrew, you can use Noto Sans Hebrew.

### Add Components

You are now ready to add components to your project. They need no RTL step of their own.

```bash
npx @webjsdev/ui add item
```

## How it works

Every component styles itself with logical utilities, which the browser resolves from the nearest `dir`:

- Padding and margin use `ps-*`, `pe-*`, `ms-*` and `me-*` instead of `pl-*`, `pr-*`, `ml-*` and `mr-*`.
- Positioning uses `start-*` and `end-*` instead of `left-*` and `right-*`.
- Text alignment and corners use `text-start`, `text-end`, `rounded-s-*` and `rounded-e-*`.
- Keyboard handling follows the visual direction. A slider's Left and Right keys swap under RTL, for example.

For your own code that has to branch on the direction, such as an arrow-key handler, the [Direction](https://webjs.dev/ui/docs/components/direction) component exports `readDirection(element)`, which reads the nearest `dir` attribute. It reads attributes only, so it also works while the page renders on the server.

```bash
npx @webjsdev/ui add direction
```

## Supported Styles

Every style supports RTL. The default style, `new-york`, is written with logical properties throughout, as are the components' own classes.

The eight styles (`vega`, `nova`, `maia`, `lyra`, `mira`, `luma`, `sera` and `rhea`) ship with a right-to-left conversion table already applied. So their physical utilities (`pl-2`, `ml-auto`, `rounded-l-md`) arrive as logical ones, and the same files render a left-to-right page exactly as before and a right-to-left one correctly.

## Font Recommendations

For the best RTL experience, we recommend using fonts that have proper support for your target language. [Noto](https://fonts.google.com/noto) is a great font family for this and it pairs well with Inter and Geist.

See Add Font above for how to install one in a WebJs app.

## Animations

A dropdown, a popover or a tooltip slides in from the side it opened on. The positioning reports that side on the panel as `data-side`, the side it was actually placed on, and the animation keys on it, so it is right in either direction.

Overlays render in the top layer through the native `<dialog>` element and the Popover API, but they stay where you wrote them in the document rather than moving to a portal. So they inherit `dir` from their ancestors like everything else.

```ts
<div dir="rtl">
  <ui-tooltip>
    <ui-tooltip-trigger>...</ui-tooltip-trigger>
    <ui-tooltip-content>...</ui-tooltip-content>
  </ui-tooltip>
</div>
```

## Icons

An icon that points a direction, like an arrow or a chevron, does not flip on its own. Add Tailwind's `rtl:rotate-180` to it:

```ts
<svg class="rtl:rotate-180" ...>...</svg>
```
