Direction

"use client"

import * as React from "react"

The DirectionProvider component sets the reading direction, and optionally the locale, for every component inside it. React Aria components read it to mirror keyboard navigation, flip sliders and carousels, and order date segments. Use it at the root of an app that supports right-to-left languages, or around one part of a page. Pass direction when you only need to flip the layout, and locale when dates, numbers, and the direction should all follow a language.

Installation#

pnpmnpmyarnbun
pnpm dlx shadcn@latest add @dots/direction
Copy

Usage#

Copyimport { DirectionProvider } from "@/components/ui/direction"

Copy<html dir="rtl">
  <body>
    <DirectionProvider direction="rtl">{children}</DirectionProvider>
  </body>
</html>

The provider tells components which way to go. It doesn't touch the DOM, so also set dir on <html> or on a wrapper element. CSS logical properties such as ms-*, ps-*, and start-* then follow it.

Features#

• A direction prop for layouts that only need to flip
• A locale prop that sets dates, numbers, and direction from one language tag
• Nesting, so one part of a page can use a different direction or locale
• useDirection and useLocale hooks to read the resolved values
• Re-exports React Aria I18nProvider for code that sets the locale only

Direction#

Pass direction="rtl" or direction="ltr". The provider keeps the current language and only switches its script, which sets the direction. Read it back with useDirection to set dir on the wrapper, as the demo at the top of this page does.

Copyfunction Panel({ children }: { children: React.ReactNode }) {
  const direction = useDirection()
  return <div dir={direction}>{children}</div>
}
 
<DirectionProvider direction="rtl">
  <Panel>{/* ... */}</Panel>
</DirectionProvider>

Locale#

Pass a locale, such as "ar-AE" or "he-IL", to format dates and numbers for that language. The direction comes from the locale, so you don't need direction too. When both are set, locale wins.

"use client"

import { CalendarDate } from "@internationalized/date"

Accessibility#

DirectionProvider wraps the React Aria I18nProvider. Components inside it:

• Swap the Left and Right arrow keys in right-to-left layouts, in sliders, tabs, toggle groups, and calendars
• Order date segments and format numbers for the locale
• Announce dates and values in the locale's format

Set dir on the DOM#

Screen readers and browsers use the dir attribute, not the provider, to read text in the right order. Always set dir on <html>, or on the wrapper of a nested section, to match the provider.

Set lang with the locale#

When you pass a locale, also set lang on the same element so screen readers pronounce the text in that language.

Copy<div lang="ar-AE" dir="rtl">
  <DirectionProvider locale="ar-AE">{children}</DirectionProvider>
</div>

API Reference#

DirectionProvider#

Sets the direction and locale for its children. Accepts all React Aria I18nProvider props.

When neither is set, the locale comes from the browser.

useDirection#

Returns the direction of the closest provider.

Copyconst direction = useDirection() // "ltr" | "rtl"

useLocale#

Returns the locale and direction of the closest provider. Re-exported from React Aria.

Copyconst { locale, direction } = useLocale()

I18nProvider#

The React Aria I18nProvider, re-exported for code that sets the locale only. See the React Aria documentation for more information.