Skip to content

feat(direction): auto-detect RTL from HTML document when no DirectionProvider is present (#3830)#3866

Open
mixelburg wants to merge 1 commit intoradix-ui:mainfrom
mixelburg:feat/auto-detect-rtl
Open

feat(direction): auto-detect RTL from HTML document when no DirectionProvider is present (#3830)#3866
mixelburg wants to merge 1 commit intoradix-ui:mainfrom
mixelburg:feat/auto-detect-rtl

Conversation

@mixelburg
Copy link
Copy Markdown

@mixelburg mixelburg commented Apr 28, 2026

What

Fixes #3830

When no DirectionProvider exists in the React tree, useDirection() currently falls back to a hardcoded 'ltr' — ignoring <html dir="rtl"> entirely. This commit adds a fallback to document.documentElement.dir so RTL apps work correctly out of the box.

How

Changed useDirection to read document.documentElement.dir as a last-resort fallback before defaulting to 'ltr':

function useDirection(localDir?: Direction) {
  const globalDir = React.useContext(DirectionContext);
  const documentDir =
    typeof document !== 'undefined'
      ? document.documentElement.dir === 'rtl' ? 'rtl' : 'ltr'
      : 'ltr';
  return localDir || globalDir || documentDir;
}

Why this is safe

  • No breaking changes: DirectionProvider still takes precedence — existing apps are unaffected
  • LTR apps unchanged: Most apps don't set <html dir="rtl">, so documentDir defaults to 'ltr'
  • SSR safe: typeof document !== 'undefined' guard handles server-side rendering
  • Dynamic: Works with runtime language switching (when dir changes on <html>)
  • Zero configuration: RTL apps work correctly without any wrapper

Who this helps

Arabic, Hebrew, Persian, and Urdu speakers (~500 million people). Every app using Radix that sets <html dir="rtl"> currently has broken RTL layout for dropdowns, dialogs, and popovers.

Checks

  • Lint passes (pnpm -r --filter @radix-ui/react-direction run lint)
  • Typecheck passes (pnpm -r --filter @radix-ui/react-direction run typecheck)

feat(direction): auto-detect RTL from HTML document when no Direction…
5adbbb9 
…Provider is present

Fixes radix-ui#3830

When no DirectionProvider exists in the React tree, useDirection() previously
fell back to a hardcoded "ltr" — ignoring <html dir="rtl"> entirely.

This commit adds a fallback to document.documentElement.dir, so RTL apps
work correctly without wrapping in DirectionProvider.

- DirectionProvider still takes precedence (no breaking changes)
- SSR safe via typeof document guard
- LTR apps unaffected (document.dir defaults to ltr)
@changeset-bot
Copy link
Copy Markdown

changeset-bot Bot commented Apr 28, 2026

⚠️ No Changeset found

Latest commit: 5adbbb9

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

feat(direction): auto-detect RTL from HTML document when no DirectionProvider is present

1 participant

@mixelburg