feat(ios): add role option to bottomTab for UITabBarSystemItem support

IsaacIsrael · cursoragent · IsaacIsrael · commit 5a9d9ed421ff · 2026-05-04T09:48:19.000+03:00
Adds a new `role` property to `OptionsBottomTab` that maps to
`UITabBarItem(tabBarSystemItem:)`. Supports all 12 system item types.

Key behaviors:
- `search` on iOS 26+ renders as a floating Liquid Glass button
- `more` activates UIKit's built-in More navigation controller
- Custom icons (`icon`, `selectedIcon`, `sfSymbol`, `sfSelectedSymbol`)
  override the system image after creation
- `iconColor` and `selectedIconColor` tint the custom icon
- Only one `search` role per bottomTabs layout (warns on duplicates)
- standardAppearance/scrollEdgeAppearance copied from the subclass
  chain onto system items to preserve tab bar styling

Includes playground demo and Detox e2e test.

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;
diff --git a/ios/BottomTabPresenter.h b/ios/BottomTabPresenter.h
@@ -2,6 +2,8 @@
 #import "RNNTabBarItemCreator.h"
 @interface BottomTabPresenter : RNNBasePresenter
 
+@property(nonatomic, strong, readonly) RNNTabBarItemCreator *tabCreator;
+
 - (instancetype)initWithDefaultOptions:(RNNNavigationOptions *)defaultOptions
                             tabCreator:(RNNTabBarItemCreator *)tabCreator;
 
diff --git a/ios/BottomTabPresenter.mm b/ios/BottomTabPresenter.mm
@@ -3,9 +3,7 @@
 #import "UIViewController+LayoutProtocol.h"
 #import "UIViewController+RNNOptions.h"
 
-@implementation BottomTabPresenter {
-    RNNTabBarItemCreator *_tabCreator;
-}
+@implementation BottomTabPresenter
 
 - (instancetype)initWithDefaultOptions:(RNNNavigationOptions *)defaultOptions
                             tabCreator:(RNNTabBarItemCreator *)tabCreator {
diff --git a/ios/RNNBottomTabOptions.h b/ios/RNNBottomTabOptions.h
@@ -25,6 +25,7 @@
 @property(nonatomic, strong) Bool *selectTabOnPress;
 @property(nonatomic, strong) Text *sfSymbol;
 @property(nonatomic, strong) Text *sfSelectedSymbol;
+@property(nonatomic, strong) Text *role;
 
 - (BOOL)hasValue;
 
diff --git a/ios/RNNBottomTabOptions.mm b/ios/RNNBottomTabOptions.mm
@@ -31,6 +31,7 @@ - (instancetype)initWithDict:(NSDictionary *)dict {
     self.selectTabOnPress = [BoolParser parse:dict key:@"selectTabOnPress"];
     self.sfSymbol = [TextParser parse:dict key:@"sfSymbol"];
     self.sfSelectedSymbol = [TextParser parse:dict key:@"sfSelectedSymbol"];
+    self.role = [TextParser parse:dict key:@"role"];
 
     return self;
 }
@@ -76,6 +77,8 @@ - (void)mergeOptions:(RNNBottomTabOptions *)options {
         self.sfSymbol = options.sfSymbol;
     if (options.sfSelectedSymbol.hasValue)
         self.sfSelectedSymbol = options.sfSelectedSymbol;
+    if (options.role.hasValue)
+        self.role = options.role;
 }
 
 - (BOOL)hasValue {
@@ -85,7 +88,7 @@ - (BOOL)hasValue {
            self.iconColor.hasValue || self.selectedIconColor.hasValue ||
            self.selectedTextColor.hasValue || self.iconInsets.hasValue || self.textColor.hasValue ||
            self.visible.hasValue || self.selectTabOnPress.hasValue || self.sfSymbol.hasValue ||
-           self.sfSelectedSymbol.hasValue;
+           self.sfSelectedSymbol.hasValue || self.role.hasValue;
 }
 
 @end
diff --git a/ios/RNNBottomTabsController.mm b/ios/RNNBottomTabsController.mm
@@ -1,4 +1,5 @@
 #import "RNNBottomTabsController.h"
+#import "RNNTabBarItemCreator.h"
 #import "UITabBarController+RNNOptions.h"
 #import "UITabBarController+RNNUtils.h"
 
@@ -95,6 +96,7 @@ - (void)viewDidLoad {
 }
 
 - (void)createTabBarItems:(NSArray<UIViewController *> *)childViewControllers {
+    _bottomTabPresenter.tabCreator.searchRoleUsed = NO;
     for (UIViewController *child in childViewControllers) {
         [_bottomTabPresenter applyOptions:child.resolveOptions child:child];
     }
diff --git a/ios/RNNTabBarItemCreator.h b/ios/RNNTabBarItemCreator.h
@@ -4,6 +4,8 @@
 
 @interface RNNTabBarItemCreator : NSObject
 
+@property(nonatomic, assign) BOOL searchRoleUsed;
+
 - (UITabBarItem *)createTabBarItem:(RNNBottomTabOptions *)bottomTabOptions
                          mergeItem:(UITabBarItem *)mergeItem;
 
diff --git a/ios/RNNTabBarItemCreator.mm b/ios/RNNTabBarItemCreator.mm
@@ -1,15 +1,46 @@
 #import "RNNTabBarItemCreator.h"
 #import "RNNFontAttributesCreator.h"
 #import "UIImage+utils.h"
+#import <React/RCTLog.h>
 
 @implementation RNNTabBarItemCreator
 
++ (NSNumber *)systemItemForRole:(NSString *)role {
+    static NSDictionary<NSString *, NSNumber *> *map = nil;
+    static dispatch_once_t onceToken;
+    dispatch_once(&onceToken, ^{
+        map = @{
+            @"search"     : @(UITabBarSystemItemSearch),
+            @"bookmarks"  : @(UITabBarSystemItemBookmarks),
+            @"contacts"   : @(UITabBarSystemItemContacts),
+            @"downloads"  : @(UITabBarSystemItemDownloads),
+            @"favorites"  : @(UITabBarSystemItemFavorites),
+            @"featured"   : @(UITabBarSystemItemFeatured),
+            @"history"    : @(UITabBarSystemItemHistory),
+            @"more"       : @(UITabBarSystemItemMore),
+            @"mostRecent" : @(UITabBarSystemItemMostRecent),
+            @"mostViewed" : @(UITabBarSystemItemMostViewed),
+            @"recents"    : @(UITabBarSystemItemRecents),
+            @"topRated"   : @(UITabBarSystemItemTopRated),
+        };
+    });
+    return map[role];
+}
+
 - (UITabBarItem *)createTabBarItem:(UITabBarItem *)mergeItem {
     return mergeItem ?: [UITabBarItem new];
 }
 
 - (UITabBarItem *)createTabBarItem:(RNNBottomTabOptions *)bottomTabOptions
                          mergeItem:(UITabBarItem *)mergeItem {
+
+    if (bottomTabOptions.role.hasValue) {
+        UITabBarItem *roleItem = [self createSystemItemForRole:bottomTabOptions
+                                                     mergeItem:mergeItem];
+        if (roleItem)
+            return roleItem;
+    }
+
     UITabBarItem *tabItem = [self createTabBarItem:mergeItem];
     UIImage *icon = [bottomTabOptions.icon withDefault:nil];
     UIImage *selectedIcon = [bottomTabOptions.selectedIcon withDefault:icon];
@@ -55,6 +86,71 @@ - (UITabBarItem *)createTabBarItem:(RNNBottomTabOptions *)bottomTabOptions
     return tabItem;
 }
 
+#pragma mark - Role (system item) creation
+
+- (UITabBarItem *)createSystemItemForRole:(RNNBottomTabOptions *)bottomTabOptions
+                                mergeItem:(UITabBarItem *)mergeItem {
+    NSString *role = [bottomTabOptions.role withDefault:nil];
+    NSNumber *systemItemNumber = [RNNTabBarItemCreator systemItemForRole:role];
+
+    if (!systemItemNumber) {
+        RCTLogWarn(@"[RNN] Unknown bottomTab role '%@' — falling back to normal tab.", role);
+        return nil;
+    }
+
+    if ([role isEqualToString:@"search"] && self.searchRoleUsed) {
+        RCTLogWarn(@"[RNN] Only one tab per bottomTabs layout may use role:'search'. "
+                   @"Subsequent 'search' roles are ignored — creating a normal tab instead.");
+        return nil;
+    }
+
+    if ([role isEqualToString:@"search"]) {
+        self.searchRoleUsed = YES;
+    }
+
+    UITabBarItem *tabItem =
+        [[UITabBarItem alloc] initWithTabBarSystemItem:(UITabBarSystemItem)[systemItemNumber integerValue]
+                                                  tag:bottomTabOptions.tag];
+
+    UITabBarItem *baseItem = [self createTabBarItem:mergeItem];
+    tabItem.standardAppearance = baseItem.standardAppearance;
+#if __IPHONE_OS_VERSION_MAX_ALLOWED >= 150000
+    if (@available(iOS 15.0, *)) {
+        tabItem.scrollEdgeAppearance = baseItem.scrollEdgeAppearance;
+    }
+#endif
+
+    UIImage *icon = [bottomTabOptions.icon withDefault:nil];
+    UIImage *selectedIcon = [bottomTabOptions.selectedIcon withDefault:nil];
+    UIColor *iconColor = [bottomTabOptions.iconColor withDefault:nil];
+    UIColor *selectedIconColor = [bottomTabOptions.selectedIconColor withDefault:iconColor];
+
+    if (@available(iOS 13.0, *)) {
+        if (bottomTabOptions.sfSymbol.hasValue) {
+            icon = [UIImage systemImageNamed:[bottomTabOptions.sfSymbol withDefault:nil]];
+        }
+        if (bottomTabOptions.sfSelectedSymbol.hasValue) {
+            selectedIcon = [UIImage systemImageNamed:[bottomTabOptions.sfSelectedSymbol withDefault:nil]];
+        }
+    }
+
+    if (icon) {
+        tabItem.image = [self getIconImage:icon withTint:iconColor];
+    }
+    if (selectedIcon) {
+        tabItem.selectedImage = [self getSelectedIconImage:selectedIcon
+                                         selectedIconColor:selectedIconColor];
+    }
+
+    tabItem.accessibilityIdentifier = [bottomTabOptions.testID withDefault:nil];
+    tabItem.accessibilityLabel = [bottomTabOptions.accessibilityLabel withDefault:nil];
+    [self appendTitleAttributes:tabItem bottomTabOptions:bottomTabOptions];
+
+    return tabItem;
+}
+
+#pragma mark - Icon helpers
+
 - (UIImage *)getSelectedIconImage:(UIImage *)selectedIcon
                 selectedIconColor:(UIColor *)selectedIconColor {
     if (selectedIcon) {
@@ -82,6 +178,8 @@ - (UIImage *)getIconImage:(UIImage *)icon withTint:(UIColor *)tintColor {
     return nil;
 }
 
+#pragma mark - Title attributes
+
 - (void)appendTitleAttributes:(UITabBarItem *)tabItem
              bottomTabOptions:(RNNBottomTabOptions *)bottomTabOptions {
     UIColor *textColor = [bottomTabOptions.textColor withDefault:[UIColor blackColor]];
diff --git a/playground/e2e/BottomTabs.test.js b/playground/e2e/BottomTabs.test.js
@@ -178,4 +178,15 @@ describe('BottomTabs', () => {
       elementByLabel('componentDidAppear | FirstBottomTabsScreen | Component')
     ).toBeVisible();
   });
+
+  describe(':ios: BottomTab Role', () => {
+    beforeEach(async () => {
+      await device.launchApp({ newInstance: true });
+      await elementById(TestIDs.BOTTOM_TABS_ROLE_BTN).tap();
+    });
+
+    it('should render a search role tab', async () => {
+      await expect(elementById(TestIDs.BOTTOM_TABS_ROLE_SEARCH_TAB)).toExist();
+    });
+  });
 });
diff --git a/playground/src/screens/LayoutsScreen.tsx b/playground/src/screens/LayoutsScreen.tsx
@@ -23,6 +23,8 @@ const {
   SIDE_MENU_BTN,
   KEYBOARD_SCREEN_BTN,
   SPLIT_VIEW_BUTTON,
+  BOTTOM_TABS_ROLE_BTN,
+  BOTTOM_TABS_ROLE_SEARCH_TAB,
 } = testIDs;
 
 interface State {
@@ -76,6 +78,12 @@ export default class LayoutsScreen extends NavigationComponent<NavigationProps,
         <Button label="Stack" testID={STACK_BTN} onPress={this.stack} />
         <Button label="BottomTabs" testID={BOTTOM_TABS_BTN} onPress={this.bottomTabs} />
         <Button label="BottomTabs Styling" onPress={this.bottomTabsStyling} />
+        <Button
+          label="BottomTabs with Role"
+          testID={BOTTOM_TABS_ROLE_BTN}
+          platform="ios"
+          onPress={this.bottomTabsWithRole}
+        />
         <Button label="SideMenu" testID={SIDE_MENU_BTN} onPress={this.sideMenu} />
         <Button label="Keyboard" testID={KEYBOARD_SCREEN_BTN} onPress={this.openKeyboardScreen} />
         <Button
@@ -139,6 +147,48 @@ export default class LayoutsScreen extends NavigationComponent<NavigationProps,
     });
   };
 
+  bottomTabsWithRole = () => {
+    Navigation.showModal({
+      bottomTabs: {
+        children: [
+          {
+            stack: {
+              children: [{ component: { name: Screens.FirstBottomTabsScreen } }],
+              options: {
+                bottomTab: {
+                  text: 'Home',
+                  icon: require('../../img/whatshot.png'),
+                },
+              },
+            },
+          },
+          {
+            stack: {
+              children: [{ component: { name: Screens.Pushed } }],
+              options: {
+                bottomTab: {
+                  text: 'Content',
+                  icon: require('../../img/layouts.png'),
+                },
+              },
+            },
+          },
+          {
+            component: {
+              name: Screens.Pushed,
+              options: {
+                bottomTab: {
+                  role: 'search',
+                  testID: BOTTOM_TABS_ROLE_SEARCH_TAB,
+                },
+              },
+            },
+          },
+        ],
+      },
+    });
+  };
+
   sideMenu = () =>
     Navigation.showModal({
       sideMenu: {
diff --git a/playground/src/testIDs.ts b/playground/src/testIDs.ts
@@ -259,6 +259,10 @@ const testIDs = {
   OPTIONS_SCREEN_HEADER: 'OPTIONS_SCREEN_HEADER',
   MODAL_SCREEN: 'MODAL_SCREEN',
   CENTERED_TEXT_HEADER: 'CENTERED_TEXT_HEADER',
+
+  // BottomTab Role
+  BOTTOM_TABS_ROLE_BTN: 'BOTTOM_TABS_ROLE_BTN',
+  BOTTOM_TABS_ROLE_SEARCH_TAB: 'BOTTOM_TABS_ROLE_SEARCH_TAB',
 };
 
 export default testIDs;
diff --git a/src/interfaces/Options.ts b/src/interfaces/Options.ts
@@ -1148,6 +1148,43 @@ export interface OptionsBottomTab {
    * #### (iOS 13+ specific)
    */
   sfSelectedSymbol?: string;
+  /**
+   * Set the tab bar item to a system-provided role.
+   * Uses `UITabBarItem(tabBarSystemItem:)` on iOS.
+   *
+   * By default the system provides the icon and title. You can
+   * override the icon by providing `icon`, `selectedIcon`,
+   * `sfSymbol`, or `sfSelectedSymbol` — they are applied after
+   * creation and replace the system-provided image.
+   * `iconColor` and `selectedIconColor` are applied as a tint
+   * to the custom icon when one is provided.
+   *
+   * **`'search'`** — on iOS 26+ this renders as a floating
+   * Liquid Glass button. Only one tab per `bottomTabs` layout
+   * may use this role; duplicates fall back to a normal tab.
+   *
+   * **`'more'`** — activates UIKit's built-in "More" navigation
+   * controller. Tabs beyond the visible limit are moved into
+   * it automatically.
+   *
+   * Properties that remain ignored for role tabs: `text`,
+   * `fontSize`, `fontFamily`, `fontWeight`, `iconInsets`.
+   *
+   * #### (iOS specific)
+   */
+  role?:
+    | 'search'
+    | 'bookmarks'
+    | 'contacts'
+    | 'downloads'
+    | 'favorites'
+    | 'featured'
+    | 'history'
+    | 'more'
+    | 'mostRecent'
+    | 'mostViewed'
+    | 'recents'
+    | 'topRated';
 }
 
 export interface SideMenuSide {

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`#import "RNNBottomTabsController.h"`
	`2`	`+#import "RNNTabBarItemCreator.h"`
`2`	`3`	`#import "UITabBarController+RNNOptions.h"`
`3`	`4`	`#import "UITabBarController+RNNUtils.h"`
`4`	`5`
`@@ -95,6 +96,7 @@ - (void)viewDidLoad {`
`95`	`96`	`}`
`96`	`97`
`97`	`98`	`- (void)createTabBarItems:(NSArray<UIViewController > )childViewControllers {`
	`99`	`+ _bottomTabPresenter.tabCreator.searchRoleUsed = NO;`
`98`	`100`	`for (UIViewController *child in childViewControllers) {`
`99`	`101`	`[_bottomTabPresenter applyOptions:child.resolveOptions child:child];`
`100`	`102`	`}`