Direction

A context provider that propagates a reading direction (LTR / RTL) to descendant components.

React exposes this as the DirectionProvider context and the useDirection() hook; Web Components ship the <gh-direction> element, which mirrors dir onto its host so the slotted subtree inherits it. React Native ships the same DirectionProvider + useDirection() — but when no provider is present it falls back to the app’s I18nManager layout direction, not 'ltr'.

Overview

DirectionProvider propagates a reading direction — 'ltr' or 'rtl' — to descendant GHDS components through React context, and useDirection() reads the nearest provider’s value. It’s behavioral only: it lets components read the direction in JS without each one inspecting the DOM.

Anatomy

The provider renders no element — it only supplies a context value. Set the matching dir attribute on your document or a wrapping element so CSS logical properties (margin-inline-start, inset-inline-end, …) resolve; the provider is the JS-readable mirror of that attribute.

Variants & States

There are no visual variants or states — the only axis is the dir value the provider carries.

State	Status	Notes
Hover	Not implemented	Renders no element.
Focus	Not implemented	—
Disabled	Not implemented	—
Loading	Not implemented	—
Error	Not implemented	—

Usage

Set the native dir attribute on a wrapping element in addition to the provider, so CSS logical properties resolve.
Read the value with useDirection() inside components that need to branch on direction in JS.
Place one provider high in the tree and let all descendants inherit it.

Don't

Don't rely on the provider alone to flip layout — it sets no dir attribute and no CSS by itself.
Don't nest conflicting providers unless a subtree genuinely needs the opposite direction.

Accessibility

Correct direction is a real accessibility requirement for right-to-left languages (Arabic, Hebrew, Persian) — text, focus order, and iconography should mirror.
The provider does not set dir on the DOM; pair it with a native dir attribute so assistive technology and the browser’s bidi algorithm get the direction too.
useDirection() returns 'ltr' when no provider is present, so components have a safe default.
See the Accessibility Guide for shared conventions.

Content

N/A — Direction carries no content. It wraps a subtree and supplies a value.

Props API

React`@ghds/react`

Prop	Type	Default	Description
`dir`	`'ltr' \| 'rtl'`	—	Reading direction applied to all descendant GHDS components. Required.
`children`	`ReactNode`	—	The subtree that reads this direction.
`useDirection()`	`() => 'ltr' \| 'rtl'`	—	Hook returning the nearest provider's direction (defaults to 'ltr').

Web Components`@ghds/web-components`

Prop	Type	Default	Description
`dir`	`'ltr' \| 'rtl'`	`'ltr'`	Reflected attribute; mirrored onto the host so the slotted subtree and CSS logical properties resolve against it.
`(default slot)`	`slot`	—	The subtree that inherits this direction.

React Native`@ghds/react-native`

Prop	Type	Default	Description
`dir`	`'ltr' \| 'rtl'`	—	Reading direction applied to all descendant GHDS components. Required (DirectionProvider).
`children`	`ReactNode`	—	The subtree that reads this direction.
`useDirection()`	`() => 'ltr' \| 'rtl'`	—	Hook returning the nearest provider's direction; falls back to the app's I18nManager layout direction when no provider is present.

Code examples

// React — @ghds/react (DirectionProvider context + useDirection hook)
import { DirectionProvider, useDirection } from '@ghds/react/direction';

<DirectionProvider dir="rtl">
  {/* descendant GHDS components read this direction */}
</DirectionProvider>;

<!-- Web Components — @ghds/web-components (mirrors `dir` onto the host) -->
<script type="module">
  import '@ghds/web-components/direction';
</script>
<gh-direction dir="rtl">
  <!-- slotted subtree inherits the direction -->
</gh-direction>

// React Native — @ghds/react-native (falls back to I18nManager when no provider is present)
import { DirectionProvider, useDirection } from '@ghds/react-native/direction';
import { Text } from '@ghds/react-native/theme';

function Price() {
  const dir = useDirection();
  return <Text>{dir === 'rtl' ? 'السعر' : 'Price'}</Text>;
}

<DirectionProvider dir="rtl">
  <Price />
</DirectionProvider>;

Live Demo

React and Web Components render live below — the same content under an LTR and an RTL direction, with the RTL column mirrored. Each column also carries a native dir attribute so logical properties resolve. React Native can’t run in a browser without additional react-native-web wiring (not set up in this site), so its usage is shown as a code sample instead.

React @ghds/react

Web Components @ghds/web-components

Balance

LTR layout

الرصيد

RTL layout