feat(Tabs): add native RTL support for bottom tabs on iOS & Android (#3613)

## Description

This PR adds proper RTL (Right-to-Left) layout support for native bottom
tabs on both iOS and Android in react-native-screens.

Previously, bottom tabs did not support the RTL direction, which caused
incorrect tab ordering and layout in RTL locales (e.g. Arabic, Hebrew).

With this change bottom tabs now support changing layout direction. This
brings native behavior in line with expected platform RTL handling and
React Native layout conventions.

### Details

@kligarski:

#### Android
On Android, the direction works out-of-the-box as it's propagated
through view hierarchy. We pass the value of the `direction` prop
directly to `TabsHost` view.

#### iOS
##### Badges
Setting `semanticContentAttribute` for `_controller.tabBar` and
`_controller.view` is not enough, e.g. badges visible through liquid
glass lens are still in LTR.


https://github.com/user-attachments/assets/0a96b18b-ddfe-4dd3-99c1-4a08a89ad86d

To handle this, we tried using the same approach as in native stack - we
set `UIView`'s `appearanceWhenContainedInInstancesOfClasses` of the tab
bar ([details how it's handled in the header are
here](https://github.com/software-mansion/react-native-screens/pull/2185/changes#diff-e5ef5b6e29f17bca80b51bc0c5faef1a44bac24e00952b30ac822520213dc6a5R504)).

However, this does not work for tab bar & sidebar on iPad starting from
iOS 18 as it is not a part of `controller.tabBar`. `_UITabContentView`
is mounted under `controller.view`. Using
`appearanceWhenContainedInInstancesOfClasses` for `_UITabContentView`
(which is already sketchy as this is an internal UIKit class) helps with
the order of items in the tab bar but the sidebar appears on the wrong
side of the screen.

That's why I decided to use modern way to handle direction via trait
overrides. For iOS prior to 17, you need to apply overrides on parent
view controller ([see
here](https://developer.apple.com/documentation/uikit/uiviewcontroller/setoverridetraitcollection(_:forchild:)?language=objc)).
This isn't the cleanest solution as the controller changes property of
the other controller which might not be a controller belonging to
`react-native-screens` but I think that this is the lesser evil. If this
turns out to be problematic, we can consider introducing some kind of
`ScreensRootView` that will ensure that there is a top controller from
`screens`.

For iOS 17+, we can use
[`traitOverrides`](https://developer.apple.com/documentation/uikit/uiviewcontroller/traitoverrides-8u19n?language=objc)
directly on the controller - this works with the top tab bar/sidebar on
iPadOS 18+.

##### ScrollView
On iOS, there is a bug with content of the ScrollView being moved off
screen after tab changes. I've reported the issue to `react-native`:
facebook/react-native#55768. The fix has been
merged (facebook/react-native#55804) and should
be available in next `react-native` release.


https://github.com/user-attachments/assets/b033d4c7-bfbe-415b-a02c-66fcfed6d0d6

##### Bottom Accessory
There seems to be a bug with bottom accessory in RTL when search role is
NOT used for one of the tabs (Apple Music and Apple Podcasts use search
role so the bug isn't visible).

| no search role (bug) | search role (no bug) |
| --- | --- |
| <video
src="https://github.com/user-attachments/assets/f5a154c0-4e52-40ca-8263-add687c23e65"
/> | <video
src="https://github.com/user-attachments/assets/cddcfab4-90b5-4387-8bea-e9c97c3b29e7"
/>

This bug is reproducible in bare UIKit app on iOS 26.2. 


https://github.com/user-attachments/assets/d0a36a07-f6a9-4bfd-9ac9-b5721a70e134

I've added this to our internal board
(https://github.com/software-mansion/react-native-screens-labs/issues/986)
and we'll check whether it has been fixed in iOS 26.3/26.4 beta.

##### Top tab bar badges

On iPadOS 18+, there seems to be a bug with the initial position of the
badges. They move to correct position after a tab change. I added a
ticket on our internal board to check whether this is a native bug:
https://github.com/software-mansion/react-native-screens-labs/issues/991.


https://github.com/user-attachments/assets/09c25789-b67c-40a1-a3e0-688043cbe17e

##### Native localization vs `react-native` on iOS

> [!IMPORTANT]
>
> When RTL is forced via `I18nManager.forceRTL(true)` but the language
of the native app isn't an RTL language, the views related to containers
such as the tab bar/sidebar by default will remain in LTR on iOS. This
is because we want to rely on native mechanism for layout direction
which is the trait system instead of `semanticContentAttribute` (used by
regular `react-native` views) which should only define whether the view
should be flipped in RTL & does not propagate down the hierarchy.
`forceRTL` does not change the trait therefore containers use layout
direction of the native app. In order to support `forceRTL`, you should
use `direction={I18nManager.isRTL ? 'rtl' : 'ltr'}` (see our example
implementation in `BottomTabsContainer.tsx`). This will override the
trait from the app with layout direction from `react-native` and
propagate it down the hierarchy.

## Changes

- add `direction` prop to `TabsHost` and implement it for both platforms
- add `Test3598.tsx`

### Before
(iOS only because Android works out of the box).
<img width="132" height="286" alt="Simulator Screenshot - iPhone 17 Pro
Max - 2026-02-03 at 18 39 51"
src="https://github.com/user-attachments/assets/19082dc4-49c7-433c-8656-37113be18d9a"
/>

### After 
#### Android
| Android Test3598 |
| --- |
| <video
src="https://github.com/user-attachments/assets/07fa151c-94b8-465e-892b-af1aa74deb83"
/> |

#### iOS
| iOS Test3598 | iOS TestBottomTabs | iOS Test3288 |
| --- | --- | --- |
| <video
src="https://github.com/user-attachments/assets/6ab88d38-df51-4869-9698-97d1b2ac2079"
/> | <video
src="https://github.com/user-attachments/assets/91d4dffc-c7a3-458c-a973-c61fefc6a2e7"
/> | <video
src="https://github.com/user-attachments/assets/dc775be4-bc07-4a82-8b42-93f54683ba84"
/> |

## Test plan
Use `Test3598`, `TestBottomTabs`, `Test3288` (iOS).

Tested on:
- Android (RTL system language enabled)
- iOS (RTL simulator + device)

## Checklist

- [x] Included code example that can be used to test this change.
- [x] For visual changes, included screenshots / GIFs / recordings
documenting the change.
- [ ] Ensured that CI passes

---------

Co-authored-by: Ahmed Awaad <ashahin@aljazirabank.com.sa>
Co-authored-by: Krzysztof Ligarski <krzysztof.ligarski@swmansion.com>

Author: 3 people

android/src/main/java/com/swmansion/rnscreens/gamma/tabs/host/TabsHostViewManager.kt

@@ -87,6 +87,11 @@ class TabsHostViewManager :
         value: String?,
     ) = Unit
 
+    override fun setLayoutDirection(
+        view: TabsHost,
+        value: String?,
+    ) = Unit
+
     override fun setColorScheme(
         view: TabsHost?,
         value: String?,

apps/src/shared/gamma/containers/bottom-tabs/BottomTabsContainer.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { Platform, type NativeSyntheticEvent } from 'react-native';
+import { I18nManager, Platform, type NativeSyntheticEvent } from 'react-native';
 import {
   Tabs,
   TabsHostProps,
@@ -81,6 +81,7 @@ export function BottomTabsContainer(props: BottomTabsContainerProps) {
       experimentalControlNavigationStateInJS={
         configWrapper.config.controlledBottomTabs
       }
+      direction={I18nManager.isRTL ? 'rtl' : 'ltr'}
       {...restProps}>
       {tabConfigs.map(tabConfig => {
         const tabKey = tabConfig.tabScreenProps.tabKey;

apps/src/tests/single-feature-tests/tabs/index.ts

@@ -6,6 +6,7 @@ import TabBarHiddenScenario from './tab-bar-hidden';
 import TabsScreenOrientationScenario from './tabs-screen-orientation';
 import TabBarAppearanceDefinedBySelectedTabScenario from './test-tabs-appearance-defined-by-selected-tab';
 import TestTabsColorScheme from './test-tabs-color-scheme';
+import TestTabsLayoutDirection from './test-tabs-layout-direction';
 
 const scenarios = {
   BottomAccessoryScenario,
@@ -14,6 +15,7 @@ const scenarios = {
   TabBarHiddenScenario,
   TabsScreenOrientationScenario,
   TestTabsColorScheme,
+  TestTabsLayoutDirection,
 };
 
 const TabsScenarioGroup: ScenarioGroup<keyof typeof scenarios> = {

apps/src/tests/single-feature-tests/tabs/test-tabs-layout-direction.tsx

@@ -0,0 +1,180 @@
+import {
+  I18nManager,
+  Platform,
+  ScrollView,
+  StyleSheet,
+  Text,
+  View,
+} from 'react-native';
+import { Scenario } from '../../shared/helpers';
+import { createAutoConfiguredTabs } from '../../shared/tabs';
+import React, { useEffect, useState } from 'react';
+import { SettingsPicker, SettingsSwitch } from '../../../shared';
+import { TabsHostProps } from 'react-native-screens';
+import useTabsConfigState from '../../shared/hooks/tabs-config';
+import { DummyScreen } from '../../shared/DummyScreens';
+
+const SCENARIO: Scenario = {
+  name: 'Layout Direction',
+  key: 'test-tabs-layout-direction',
+  details:
+    'Tests how tabs handle system, React Native and prop layout direction.',
+  platforms: ['android', 'ios'],
+  AppComponent: App,
+};
+
+export default SCENARIO;
+
+type TabsParamList = {
+  Config: undefined;
+  Tab2: undefined;
+};
+
+function ConfigScreen() {
+  const [config, dispatch] = useTabsConfigState<TabsParamList>();
+  const [reactForceRtl, setReactForceRtl] = useState(false);
+  const [reactAllowRtl, setReactAllowRtl] = useState(true);
+
+  // TODO: Tabs.Autoconfig should allow initial prop configuration.
+  useEffect(() => {
+    dispatch({
+      type: 'tabScreen',
+      tabKey: 'Config',
+      config: {
+        safeAreaConfiguration: {
+          edges: {
+            bottom: true,
+          },
+        },
+      },
+    });
+  }, [dispatch]);
+
+  useEffect(() => {
+    I18nManager.forceRTL(reactForceRtl);
+  }, [reactForceRtl]);
+
+  useEffect(() => {
+    I18nManager.allowRTL(reactAllowRtl);
+  }, [reactAllowRtl]);
+
+  return (
+    <ScrollView style={styles.container} contentContainerStyle={styles.content}>
+      <View style={styles.section}>
+        <Text>
+          There are 3 sources of layout direction: system, React Native and our
+          property on TabsHost.
+        </Text>
+      </View>
+
+      <View style={styles.section}>
+        <Text style={styles.heading}>System layout direction</Text>
+        <Text>
+          System layout direction depends on the language of the device
+          (Android/iOS) and supportRtl in app manifest (Android) or available
+          localizations in Xcode (iOS). In Xcode remember that you must select
+          the language as default or provide at least 1 localization file (e.g.
+          empty ar.lproj/InfoPlist.strings).
+        </Text>
+      </View>
+
+      <View style={styles.section}>
+        <Text style={styles.heading}>React Native's isRTL</Text>
+        <Text style={styles.rtlInfo}>
+          {'I18nManager.isRTL == ' + (I18nManager.isRTL ? 'true' : 'false')}
+        </Text>
+      </View>
+
+      <View style={styles.section}>
+        <Text style={styles.heading}>React Native's forceRTL</Text>
+        <Text style={styles.description}>
+          Initial value might be incorrect. Remember to restart the app after
+          the change!
+        </Text>
+        <SettingsSwitch
+          label={'forceRTL'}
+          value={reactForceRtl}
+          onValueChange={function (value: boolean): void {
+            setReactForceRtl(value);
+          }}
+        />
+      </View>
+
+      <View style={styles.section}>
+        <Text style={styles.heading}>React Native's allowRTL</Text>
+        <Text style={styles.description}>
+          Initial value might be incorrect. Remember to restart the app after
+          the change!
+        </Text>
+        <SettingsSwitch
+          label={'allowRTL'}
+          value={reactAllowRtl}
+          onValueChange={function (value: boolean): void {
+            setReactAllowRtl(value);
+          }}
+        />
+      </View>
+
+      <View style={styles.section}>
+        <Text style={styles.heading}>TabsHost layout direction</Text>
+        <SettingsPicker<NonNullable<TabsHostProps['direction']>>
+          label={'direction'}
+          value={config.direction ?? 'inherit'}
+          onValueChange={function (value: TabsHostProps['direction']): void {
+            dispatch({
+              type: 'tabBar',
+              config: {
+                direction: value,
+              },
+            });
+          }}
+          items={['inherit', 'ltr', 'rtl']}
+        />
+      </View>
+    </ScrollView>
+  );
+}
+
+const Tabs = createAutoConfiguredTabs<TabsParamList>({
+  Config: ConfigScreen,
+  Tab2: DummyScreen,
+});
+
+export function App() {
+  return (
+    <Tabs.Provider>
+      <Tabs.Autoconfig />
+    </Tabs.Provider>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  containerCenter: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  content: {
+    padding: 20,
+    paddingTop: Platform.OS === 'android' ? 60 : undefined,
+  },
+  heading: {
+    fontSize: 24,
+    fontWeight: 'bold',
+    marginBottom: 5,
+  },
+  description: {
+    marginBottom: 5,
+  },
+  rtlInfo: {
+    fontWeight: 'bold',
+    textAlign: 'center',
+    marginVertical: 5,
+  },
+  section: {
+    marginBottom: 10,
+  },
+});

common/cpp/react/renderer/components/rnscreens/RNSTabsBottomAccessoryShadowNode.cpp

@@ -11,4 +11,21 @@ Point RNSTabsBottomAccessoryShadowNode::getContentOriginOffset(
   return stateData.contentOffset;
 }
 
+void RNSTabsBottomAccessoryShadowNode::layout(
+    facebook::react::LayoutContext layoutContext) {
+  YogaLayoutableShadowNode::layout(layoutContext);
+  applyFrameCorrections();
+}
+
+// When calculating content origin offset for bottom accessory we rely on the
+// fact that it's positioned at (0,0). In RTL, this is not the case. As we don't
+// want to change `direction` (as this change would propagate further down the
+// hierarchy), we force x=0 in the shadow node. If this approach turns out to be
+// problematic, we can consider adjusting content origin offset to account for
+// the "incorrect" layout in RTL.
+void RNSTabsBottomAccessoryShadowNode::applyFrameCorrections() {
+  ensureUnsealed();
+  layoutMetrics_.frame.origin.x = 0;
+}
+
 } // namespace facebook::react

common/cpp/react/renderer/components/rnscreens/RNSTabsBottomAccessoryShadowNode.h

@@ -4,6 +4,7 @@
 #include <react/renderer/components/rnscreens/EventEmitters.h>
 #include <react/renderer/components/rnscreens/Props.h>
 #include <react/renderer/components/view/ConcreteViewShadowNode.h>
+#include <react/renderer/core/LayoutContext.h>
 #include "RNSTabsBottomAccessoryState.h"
 
 namespace facebook::react {
@@ -20,7 +21,15 @@ class JSI_EXPORT RNSTabsBottomAccessoryShadowNode final
   using ConcreteViewShadowNode::ConcreteViewShadowNode;
   using StateData = ConcreteViewShadowNode::ConcreteStateData;
 
+#pragma mark - ShadowNode overrides
+
   Point getContentOriginOffset(bool includeTransform) const override;
+
+  void layout(LayoutContext layoutContext) override;
+
+#pragma mark - Custom interface
+ private:
+  void applyFrameCorrections();
 };
 
 } // namespace facebook::react

ios/conversion/RNSConversions-Tabs.mm

@@ -484,6 +484,23 @@ UIUserInterfaceStyle UIUserInterfaceStyleFromTabsScreenCppEquivalent(
   }
 }
 
+UITraitEnvironmentLayoutDirection UITraitEnvironmentLayoutDirectionFromTabsHostCppEquivalent(
+    react::RNSTabsHostLayoutDirection layoutDirection)
+{
+  using enum facebook::react::RNSTabsHostLayoutDirection;
+  switch (layoutDirection) {
+    case Inherit:
+      return UITraitEnvironmentLayoutDirectionUnspecified;
+    case Ltr:
+      return UITraitEnvironmentLayoutDirectionLeftToRight;
+    case Rtl:
+      return UITraitEnvironmentLayoutDirectionRightToLeft;
+    default:
+      RCTLogError(@"[RNScreens] unsupported layout direction");
+      return UITraitEnvironmentLayoutDirectionUnspecified;
+  }
+}
+
 UIUserInterfaceStyle UIUserInterfaceStyleFromHostProp(react::RNSTabsHostColorScheme colorScheme)
 {
   using enum facebook::react::RNSTabsHostColorScheme;

ios/conversion/RNSConversions.h

@@ -108,6 +108,9 @@ UIInterfaceOrientationMask UIInterfaceOrientationMaskFromRNSOrientation(RNSOrien
 RNSOrientation RNSOrientationFromUIInterfaceOrientationMask(UIInterfaceOrientationMask orientationMask);
 #endif // !TARGET_OS_TV
 
+UITraitEnvironmentLayoutDirection UITraitEnvironmentLayoutDirectionFromTabsHostCppEquivalent(
+    react::RNSTabsHostLayoutDirection layoutDirection);
+
 UIUserInterfaceStyle UIUserInterfaceStyleFromHostProp(react::RNSTabsHostColorScheme colorScheme);
 
 #pragma mark SplitHost props

ios/tabs/host/RNSTabBarController.h

@@ -118,6 +118,30 @@ NS_ASSUME_NONNULL_BEGIN
  */
 - (void)updateOrientation;
 
+/**
+ * Updates the layout direction based on property on host view.
+ *
+ * This method does nothing if the update has not been previously requested.
+ * If needed, the requested update is performed immediately. If you do not need this, consider just raising an
+ * appropriate invalidation signal & let the controller decide when to flush the updates.
+ *
+ * This method is necessary only on iOS versions prior to 17.
+ * On iOS 17+, use `traitOverrides.layoutDirection` on the controller directly.
+ */
+- (void)updateLayoutDirectionBelowIOS17IfNeeded;
+
+/**
+ * Updates the layout direction based on property on host view.
+ *
+ * The requested update is performed immediately. If you do not need this, consider just raising an appropriate
+ * invalidation signal & let the controller decide when to flush the updates.
+ *
+ * This method is necessary only on iOS versions prior to 17.
+ * On iOS 17+, use `traitOverrides.layoutDirection` on the controller directly.
+ *
+ * This method can only be called when `parentViewController` is not nil.
+ */
+- (void)updateLayoutDirectionBelowIOS17;
 @end
 
 #pragma mark - Signals
@@ -161,6 +185,14 @@ NS_ASSUME_NONNULL_BEGIN
  */
 @property (nonatomic, readwrite) bool needsOrientationUpdate;
 
+/**
+ * Tell the controller that some configuration regarding layout direction has changed & it requires update.
+ *
+ * This flag is necessary only on iOS versions prior to 17.
+ * On iOS 17+, use `traitOverrides.layoutDirection` on the controller directly.
+ */
+@property (nonatomic, readwrite) bool needsLayoutDirectionUpdateBelowIOS17;
+
 @end
 
 NS_ASSUME_NONNULL_END