Document direction prop and useLocale

react-navigation · Jun 26, 2024 · c9cec95 · c9cec95
1 parent 57c00dc
commit c9cec95
Show file tree

Hide file tree

Showing 2 changed files with 36 additions and 0 deletions.
diff --git a/versioned_docs/version-7.x/navigation-container.md b/versioned_docs/version-7.x/navigation-container.md
@@ -911,6 +911,34 @@ Example:
 
 Custom theme to use for the navigation components such as the header, tab bar etc. See [theming guide](themes.md) for more details and usage guide.
 
+### `direction`
+
+The direction of the text in the app. Defaults to `'rtl'` when `I18nManager.getConstants().isRTL` is `true`, otherwise `'ltr'`.
+
+This is used in various navigators to adjust the content according to the text direction, for example, the drawer in the [drawer navigator](drawer-navigator.md) is positioned on the right side in RTL languages.
+
+If you intend to support RTL languages, it's important to set this prop to the correct value. If it doesn't match the actual text direction, the layout might be incorrect.
+
+On the Web, it may also be necessary to set the `dir` attribute on the root element of the app to ensure that the text direction is correct:
+
+```html
+<html dir="rtl">
+  <!-- App content -->
+</html>
+```
+
+The `direction` will be available to use in your own components via the `useLocale` hook:
+
+```js
+import { useLocale } from '@react-navigation/native';
+
+function MyComponent() {
+  const { direction } = useLocale();
+
+  // Use the direction
+}
+```
+
 ### `navigationInChildEnabled`
 
 :::warning

diff --git a/versioned_docs/version-7.x/upgrading-from-6.x.md b/versioned_docs/version-7.x/upgrading-from-6.x.md
@@ -539,6 +539,14 @@ const options = ({
 };
 ```
 
+### Improved RTL support
+
+Previously, various UI elements used the `I18nManager` API to determine the writing direction. However, this API doesn't work well on the Web as the writing direction can be different for a specific subtree and hence can't be determined globally.
+
+The `NavigationContainer` now accepts a `direction` prop to specify the direction of the layout instead of relying on the `I18nManager` API. It also exposes this value via `useLocale` hook for use in your own components.
+
+See the [navigation container docs](navigation-container.md#direction) for usage.
+
 ### The `options` callback gets `theme`
 
 The `options` callback now receives the `theme` object to allow customizing the UI elements specified in the options: