From b41d77b8452d24400a0bb129d351f6e85432db9e Mon Sep 17 00:00:00 2001
From: D N <4661784+retyui@users.noreply.github.com>
Date: Sun, 20 Sep 2026 00:11:44 +0200
Subject: [PATCH 1/7] New role `prominent` (SDK27+)

---
 .../docs/docs/guides/usage-with-react-navigation.mdx |  1 +
 .../ios/TabView/NewTabView.swift                     |  2 +-
 .../react-native-bottom-tabs/ios/TabViewImpl.swift   |  2 +-
 .../react-native-bottom-tabs/ios/TabViewProps.swift  | 12 +++++++++++-
 packages/react-native-bottom-tabs/src/types.ts       |  2 +-
 5 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/docs/docs/docs/guides/usage-with-react-navigation.mdx b/docs/docs/docs/guides/usage-with-react-navigation.mdx
index 78e49d55..2622b962 100644
--- a/docs/docs/docs/guides/usage-with-react-navigation.mdx
+++ b/docs/docs/docs/guides/usage-with-react-navigation.mdx
@@ -403,6 +403,7 @@ A value that defines the purpose of the tab. This can be used to pin and separat
 Available options:
 
 - `search` - The search role.
+- `prominent` - Mark one tab as visually more important than the others (`SDK 27+`).
 
 #### `sceneStyle`
 
diff --git a/packages/react-native-bottom-tabs/ios/TabView/NewTabView.swift b/packages/react-native-bottom-tabs/ios/TabView/NewTabView.swift
index 2f18f210..c817bc7e 100644
--- a/packages/react-native-bottom-tabs/ios/TabView/NewTabView.swift
+++ b/packages/react-native-bottom-tabs/ios/TabView/NewTabView.swift
@@ -38,7 +38,7 @@ struct NewTabView: AnyTabView {
               onSelect: onSelect
             )
 
-            Tab(value: tabData.key, role: tabData.role?.convert()) {
+            Tab(value: tabData.key, role: tabData.role.flatMap { $0.convert() }) {
               RepresentableView(view: child.view)
                 .ignoresSafeArea(.container, edges: .all)
                 .tabAppear(using: context)
diff --git a/packages/react-native-bottom-tabs/ios/TabViewImpl.swift b/packages/react-native-bottom-tabs/ios/TabViewImpl.swift
index 68053e1f..14286c69 100644
--- a/packages/react-native-bottom-tabs/ios/TabViewImpl.swift
+++ b/packages/react-native-bottom-tabs/ios/TabViewImpl.swift
@@ -233,7 +233,7 @@ struct TabViewImpl: View {
       let preservesOriginalIconColors = preservesOriginalIconColors(tabData: tabData)
       let useBakedTintColors = shouldUseExperimentalBakedTintColors(props: props)
       let shouldRenderLabelIntoImage =
-        props.hasCustomTintColors && props.labeled && tabData.role != .search && icon != nil
+        props.hasCustomTintColors && props.labeled && tabData.role == nil && icon != nil
 
       item.accessibilityLabel = tabData.title
 
diff --git a/packages/react-native-bottom-tabs/ios/TabViewProps.swift b/packages/react-native-bottom-tabs/ios/TabViewProps.swift
index dd4c3c88..19e2290e 100644
--- a/packages/react-native-bottom-tabs/ios/TabViewProps.swift
+++ b/packages/react-native-bottom-tabs/ios/TabViewProps.swift
@@ -30,12 +30,22 @@ internal enum MinimizeBehavior: String {
 
 public enum TabBarRole: String {
   case search
+  case prominent
 
   @available(iOS 18, macOS 15, visionOS 2, tvOS 18, *)
-  func convert() -> TabRole {
+  func convert() -> TabRole? {
     switch self {
     case .search:
       return .search
+    case .prominent:
+      #if compiler(>=6.4)
+        if #available(iOS 27, macOS 27, visionOS 27, tvOS 27, *) {
+          return .prominent
+        }
+      #endif
+      // `.prominent` role was introduced in iOS 27 SDK; ignore it on older OS versions
+      // instead of crashing or silently mapping to the wrong role.
+      return nil
     }
   }
 }
diff --git a/packages/react-native-bottom-tabs/src/types.ts b/packages/react-native-bottom-tabs/src/types.ts
index 3f4eda80..84223786 100644
--- a/packages/react-native-bottom-tabs/src/types.ts
+++ b/packages/react-native-bottom-tabs/src/types.ts
@@ -5,7 +5,7 @@ export type IconSource = string | ImageSourcePropType;
 
 export type AppleIcon = { sfSymbol: SFSymbol };
 
-export type TabRole = 'search';
+export type TabRole = 'search' | 'prominent';
 
 export type IconRenderingMode = 'automatic' | 'original';
 

From b1927fe6a36cf71fea9f9d8d01df40040c218231 Mon Sep 17 00:00:00 2001
From: Thiago Brezinski <thiagobrez@gmail.com>
Date: Tue, 22 Sep 2026 14:13:05 +0100
Subject: [PATCH 2/7] Add iOS tab role example

- Add an example for switching between search and prominent tab roles
- Demonstrate experimental baked tint colors
---
 packages/example-shared/src/App.tsx           |   2 +
 .../example-shared/src/Examples/Roles.tsx     | 109 ++++++++++++++++++
 2 files changed, 111 insertions(+)
 create mode 100644 packages/example-shared/src/Examples/Roles.tsx

diff --git a/packages/example-shared/src/App.tsx b/packages/example-shared/src/App.tsx
index 5e70681a..420d3427 100644
--- a/packages/example-shared/src/App.tsx
+++ b/packages/example-shared/src/App.tsx
@@ -28,6 +28,7 @@ import SixTabs from './Examples/SixTabs';
 import FourTabsRTL from './Examples/FourTabsRTL';
 import MaterialBottomTabs from './Examples/MaterialBottomTabs';
 import SFSymbols from './Examples/SFSymbols';
+import Roles from './Examples/Roles';
 import LabeledTabs from './Examples/Labeled';
 import NativeBottomTabs from './Examples/NativeBottomTabs';
 import TintColorsExample from './Examples/TintColors';
@@ -99,6 +100,7 @@ const examples = [
   { component: FourTabs, name: 'Four Tabs' },
   { component: FiveTabs, name: 'Five Tabs' },
   { component: SixTabs, name: 'Six Tabs' },
+  { component: Roles, name: 'Roles', platform: 'ios' },
   {
     component: SFSymbols,
     name: 'SF Symbols',
diff --git a/packages/example-shared/src/Examples/Roles.tsx b/packages/example-shared/src/Examples/Roles.tsx
new file mode 100644
index 00000000..319f1d22
--- /dev/null
+++ b/packages/example-shared/src/Examples/Roles.tsx
@@ -0,0 +1,109 @@
+import { useState } from 'react';
+import { Button, StyleSheet, Switch, Text, View } from 'react-native';
+import TabView, { SceneMap } from 'react-native-bottom-tabs';
+import type { TabRole } from 'react-native-bottom-tabs';
+import { Article } from '../Screens/Article';
+import { Albums } from '../Screens/Albums';
+import { Contacts } from '../Screens/Contacts';
+
+const renderScene = SceneMap({
+  article: Article,
+  albums: Albums,
+  role: Contacts,
+});
+
+export default function Roles() {
+  const [role, setRole] = useState<TabRole>('search');
+  const [bakedTintColors, setBakedTintColors] = useState(false);
+
+  return (
+    <View style={styles.container}>
+      <View style={styles.controls}>
+        <View style={styles.row}>
+          <Button
+            title="Search"
+            disabled={role === 'search'}
+            onPress={() => setRole('search')}
+          />
+          <Button
+            title="Prominent"
+            disabled={role === 'prominent'}
+            onPress={() => setRole('prominent')}
+          />
+        </View>
+        <Text>
+          {role === 'search'
+            ? 'Search role (iOS 18+). May receive prominent styling when no tab has the prominent role.'
+            : 'Prominent role (iOS 27+). Emphasizes the Contacts tab; falls back to an ordinary tab on older iOS versions.'}
+        </Text>
+        <View style={styles.row}>
+          <Text>Experimental baked tint colors</Text>
+          <Switch
+            accessibilityLabel="Experimental baked tint colors"
+            value={bakedTintColors}
+            onValueChange={setBakedTintColors}
+          />
+        </View>
+      </View>
+      <RoleTabs key={role} role={role} bakedTintColors={bakedTintColors} />
+    </View>
+  );
+}
+
+function RoleTabs({
+  role,
+  bakedTintColors,
+}: {
+  role: TabRole;
+  bakedTintColors: boolean;
+}) {
+  const [index, setIndex] = useState(0);
+  const [routes] = useState([
+    {
+      key: 'article',
+      title: 'Article',
+      focusedIcon: { sfSymbol: 'doc.text' },
+    },
+    {
+      key: 'albums',
+      title: 'Albums',
+      focusedIcon: { sfSymbol: 'square.grid.2x2' },
+    },
+    {
+      key: 'role',
+      title: role === 'search' ? 'Search' : 'Contacts',
+      focusedIcon: {
+        sfSymbol: role === 'search' ? 'magnifyingglass' : 'person.crop.circle',
+      },
+      role,
+      testID: `roles-${role}-tab`,
+    },
+  ]);
+
+  return (
+    <TabView
+      navigationState={{ index, routes }}
+      onIndexChange={setIndex}
+      renderScene={renderScene}
+      labeled
+      tabBarActiveTintColor="red"
+      tabBarInactiveTintColor="orange"
+      experimental_bakedTintColors={bakedTintColors}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  controls: {
+    padding: 12,
+    gap: 12,
+  },
+  row: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+  },
+});

From 84d3a2dcd348f9891d2b9ce30f1b08f8f1550537 Mon Sep 17 00:00:00 2001
From: Thiago Brezinski <thiagobrez@gmail.com>
Date: Tue, 22 Sep 2026 14:48:25 +0100
Subject: [PATCH 3/7] fix(ios): preserve label baking for unsupported tab roles

---
 packages/react-native-bottom-tabs/ios/TabViewImpl.swift | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/packages/react-native-bottom-tabs/ios/TabViewImpl.swift b/packages/react-native-bottom-tabs/ios/TabViewImpl.swift
index 14286c69..80ee9ade 100644
--- a/packages/react-native-bottom-tabs/ios/TabViewImpl.swift
+++ b/packages/react-native-bottom-tabs/ios/TabViewImpl.swift
@@ -232,8 +232,14 @@ struct TabViewImpl: View {
         props.focusedIcons[itemIndex] ?? makeSFSymbolImage(named: tabData.focusedSfSymbol) ?? icon
       let preservesOriginalIconColors = preservesOriginalIconColors(tabData: tabData)
       let useBakedTintColors = shouldUseExperimentalBakedTintColors(props: props)
+      let hasEffectiveRole: Bool
+      if #available(iOS 18, macOS 15, visionOS 2, tvOS 18, *) {
+        hasEffectiveRole = tabData.role?.convert() != nil
+      } else {
+        hasEffectiveRole = false
+      }
       let shouldRenderLabelIntoImage =
-        props.hasCustomTintColors && props.labeled && tabData.role == nil && icon != nil
+        props.hasCustomTintColors && props.labeled && !hasEffectiveRole && icon != nil
 
       item.accessibilityLabel = tabData.title
 

From 475128c4421ccda39af5d4d7099c91c1379fb576 Mon Sep 17 00:00:00 2001
From: Thiago Brezinski <thiagobrez@gmail.com>
Date: Wed, 23 Sep 2026 00:00:28 +0100
Subject: [PATCH 4/7] chore: improve Roles example

---
 .../example-shared/src/Examples/Roles.tsx     | 92 +++++++++----------
 1 file changed, 45 insertions(+), 47 deletions(-)

diff --git a/packages/example-shared/src/Examples/Roles.tsx b/packages/example-shared/src/Examples/Roles.tsx
index 319f1d22..ddfbff4b 100644
--- a/packages/example-shared/src/Examples/Roles.tsx
+++ b/packages/example-shared/src/Examples/Roles.tsx
@@ -1,4 +1,4 @@
-import { useState } from 'react';
+import { useMemo, useState } from 'react';
 import { Button, StyleSheet, Switch, Text, View } from 'react-native';
 import TabView, { SceneMap } from 'react-native-bottom-tabs';
 import type { TabRole } from 'react-native-bottom-tabs';
@@ -15,6 +15,37 @@ const renderScene = SceneMap({
 export default function Roles() {
   const [role, setRole] = useState<TabRole>('search');
   const [bakedTintColors, setBakedTintColors] = useState(false);
+  const [index, setIndex] = useState(0);
+  const routes = useMemo(
+    () => [
+      {
+        key: 'article',
+        title: 'Article',
+        focusedIcon: { sfSymbol: 'document' },
+      },
+      {
+        key: 'albums',
+        title: 'Albums',
+        focusedIcon: { sfSymbol: 'square.grid.2x2' },
+      },
+      {
+        key: 'role',
+        title: role === 'search' ? 'Search' : 'Contacts',
+        focusedIcon: {
+          sfSymbol:
+            role === 'search' ? 'magnifyingglass' : 'person.crop.circle',
+        },
+        role,
+        testID: `roles-${role}-tab`,
+      },
+    ],
+    [role]
+  );
+
+  const selectRole = (nextRole: TabRole) => {
+    setIndex(0);
+    setRole(nextRole);
+  };
 
   return (
     <View style={styles.container}>
@@ -23,12 +54,12 @@ export default function Roles() {
           <Button
             title="Search"
             disabled={role === 'search'}
-            onPress={() => setRole('search')}
+            onPress={() => selectRole('search')}
           />
           <Button
             title="Prominent"
             disabled={role === 'prominent'}
-            onPress={() => setRole('prominent')}
+            onPress={() => selectRole('prominent')}
           />
         </View>
         <Text>
@@ -45,54 +76,21 @@ export default function Roles() {
           />
         </View>
       </View>
-      <RoleTabs key={role} role={role} bakedTintColors={bakedTintColors} />
+      <TabView
+        key={role}
+        navigationState={{ index, routes }}
+        onIndexChange={setIndex}
+        renderScene={renderScene}
+        labeled
+        tabBarActiveTintColor="red"
+        tabBarInactiveTintColor="orange"
+        experimental_bakedTintColors={bakedTintColors}
+        minimizeBehavior='onScrollDown'
+      />
     </View>
   );
 }
 
-function RoleTabs({
-  role,
-  bakedTintColors,
-}: {
-  role: TabRole;
-  bakedTintColors: boolean;
-}) {
-  const [index, setIndex] = useState(0);
-  const [routes] = useState([
-    {
-      key: 'article',
-      title: 'Article',
-      focusedIcon: { sfSymbol: 'doc.text' },
-    },
-    {
-      key: 'albums',
-      title: 'Albums',
-      focusedIcon: { sfSymbol: 'square.grid.2x2' },
-    },
-    {
-      key: 'role',
-      title: role === 'search' ? 'Search' : 'Contacts',
-      focusedIcon: {
-        sfSymbol: role === 'search' ? 'magnifyingglass' : 'person.crop.circle',
-      },
-      role,
-      testID: `roles-${role}-tab`,
-    },
-  ]);
-
-  return (
-    <TabView
-      navigationState={{ index, routes }}
-      onIndexChange={setIndex}
-      renderScene={renderScene}
-      labeled
-      tabBarActiveTintColor="red"
-      tabBarInactiveTintColor="orange"
-      experimental_bakedTintColors={bakedTintColors}
-    />
-  );
-}
-
 const styles = StyleSheet.create({
   container: {
     flex: 1,

From 8b31dec0b26de3a95dbc82880b742e9fa0484ccb Mon Sep 17 00:00:00 2001
From: Thiago Brezinski <thiagobrez@gmail.com>
Date: Wed, 23 Sep 2026 23:37:50 +0100
Subject: [PATCH 5/7] fix(iOS): refresh prominent tab styling after selection

---
 .../ios/TabViewImpl.swift                     | 32 +++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/packages/react-native-bottom-tabs/ios/TabViewImpl.swift b/packages/react-native-bottom-tabs/ios/TabViewImpl.swift
index 80ee9ade..4405731e 100644
--- a/packages/react-native-bottom-tabs/ios/TabViewImpl.swift
+++ b/packages/react-native-bottom-tabs/ios/TabViewImpl.swift
@@ -11,6 +11,9 @@ struct TabViewImpl: View {
   #else
     @Weak var tabBar: UITabBar?
   #endif
+  #if os(iOS)
+    @Weak var tabBarController: UITabBarController?
+  #endif
 
   @ViewBuilder
   var tabContent: some View {
@@ -70,6 +73,9 @@ struct TabViewImpl: View {
           tabBar = tabController
         #else
           tabBar = tabController.tabBar
+          #if os(iOS)
+            tabBarController = tabController
+          #endif
           updateTabBarAppearance(props: props, tabBar: tabController.tabBar)
           updateTabBarItemImages(props: props, tabBar: tabController.tabBar)
           if !props.tabBarHidden {
@@ -96,6 +102,9 @@ struct TabViewImpl: View {
         #if os(tvOS) || os(macOS) || os(visionOS)
           onSelect(newValue)
         #endif
+        #if os(iOS)
+          refreshProminentTab(tabBarController: tabBarController)
+        #endif
       }
   }
 
@@ -142,6 +151,29 @@ struct TabViewImpl: View {
   }
 #endif
 
+#if os(iOS)
+  /// Workaround to a SwiftUI bug.
+  /// On iOS 27, the prominent tab keeps its selected styling after another tab is selected
+  /// if the tab bar was updated during its selection animation (e.g. item images being
+  /// reconfigured, or React re-rendering in response to the selection).
+  /// Re-assigning the prominent tab identifier makes UIKit rebuild the prominent tab button.
+  private func refreshProminentTab(tabBarController: UITabBarController?) {
+    #if compiler(>=6.4)
+      guard #available(iOS 27, *) else { return }
+
+      DispatchQueue.main.async { [weak tabBarController] in
+        guard let tabBarController,
+          let identifier = tabBarController.prominentTabIdentifier,
+          tabBarController.selectedTab?.identifier != identifier
+        else { return }
+
+        tabBarController.setProminentTabIdentifier(nil, animated: false)
+        tabBarController.setProminentTabIdentifier(identifier, animated: false)
+      }
+    #endif
+  }
+#endif
+
 #if !os(macOS)
   private func configureTransparentAppearance(tabBar: UITabBar, props: TabViewProps) {
     tabBar.barTintColor = props.barTintColor

From adb84fda630a5e43340b4c9315d046d44cf37859 Mon Sep 17 00:00:00 2001
From: Thiago Brezinski <thiagobrez@gmail.com>
Date: Thu, 24 Sep 2026 14:07:54 +0100
Subject: [PATCH 6/7] fix(iOS): stabilize iOS 27 tab selection styling

- Add the `prominent` tab role for iOS 27+
- Cache tab item images and avoid image updates during tab bar animations
---
 .changeset/ios-prominent-tab-role.md          |   5 +
 .../ios/TabView/NewTabView.swift              |  11 +-
 .../ios/TabViewImpl.swift                     | 237 ++++++++++++------
 .../ios/TabViewProps.swift                    |   3 +
 4 files changed, 170 insertions(+), 86 deletions(-)
 create mode 100644 .changeset/ios-prominent-tab-role.md

diff --git a/.changeset/ios-prominent-tab-role.md b/.changeset/ios-prominent-tab-role.md
new file mode 100644
index 00000000..340cc1d1
--- /dev/null
+++ b/.changeset/ios-prominent-tab-role.md
@@ -0,0 +1,5 @@
+---
+'react-native-bottom-tabs': minor
+---
+
+Add the `prominent` tab role (iOS 27+), and fix iOS 27 tabs keeping their selected tint after switching tabs or minimizing the tab bar
diff --git a/packages/react-native-bottom-tabs/ios/TabView/NewTabView.swift b/packages/react-native-bottom-tabs/ios/TabView/NewTabView.swift
index c817bc7e..bc9e6eff 100644
--- a/packages/react-native-bottom-tabs/ios/TabView/NewTabView.swift
+++ b/packages/react-native-bottom-tabs/ios/TabView/NewTabView.swift
@@ -28,7 +28,11 @@ struct NewTabView: AnyTabView {
           let isFocused = props.selectedPage == tabData.key
 
           if !tabData.hidden || isFocused {
-            let icon = props.icons[index]
+            #if os(macOS)
+              let labelImage: PlatformImage? = nil
+            #else
+              let labelImage = props.itemImages.images(for: tabData, props: props)?.labelImage
+            #endif
 
             let context = TabAppearContext(
               index: index,
@@ -46,10 +50,11 @@ struct NewTabView: AnyTabView {
             } label: {
               TabItem(
                 title: tabData.title,
-                icon: icon,
+                icon: labelImage ?? props.icons[index],
                 sfSymbol: tabData.sfSymbol,
                 labeled: props.labeled,
-                iconRenderingMode: tabData.iconRenderingMode
+                // Rendered label images already have their final rendering mode.
+                iconRenderingMode: labelImage == nil ? tabData.iconRenderingMode : nil
               )
             }
             #if !os(tvOS)
diff --git a/packages/react-native-bottom-tabs/ios/TabViewImpl.swift b/packages/react-native-bottom-tabs/ios/TabViewImpl.swift
index 4405731e..ad493310 100644
--- a/packages/react-native-bottom-tabs/ios/TabViewImpl.swift
+++ b/packages/react-native-bottom-tabs/ios/TabViewImpl.swift
@@ -11,9 +11,6 @@ struct TabViewImpl: View {
   #else
     @Weak var tabBar: UITabBar?
   #endif
-  #if os(iOS)
-    @Weak var tabBarController: UITabBarController?
-  #endif
 
   @ViewBuilder
   var tabContent: some View {
@@ -73,9 +70,6 @@ struct TabViewImpl: View {
           tabBar = tabController
         #else
           tabBar = tabController.tabBar
-          #if os(iOS)
-            tabBarController = tabController
-          #endif
           updateTabBarAppearance(props: props, tabBar: tabController.tabBar)
           updateTabBarItemImages(props: props, tabBar: tabController.tabBar)
           if !props.tabBarHidden {
@@ -102,9 +96,6 @@ struct TabViewImpl: View {
         #if os(tvOS) || os(macOS) || os(visionOS)
           onSelect(newValue)
         #endif
-        #if os(iOS)
-          refreshProminentTab(tabBarController: tabBarController)
-        #endif
       }
   }
 
@@ -151,29 +142,6 @@ struct TabViewImpl: View {
   }
 #endif
 
-#if os(iOS)
-  /// Workaround to a SwiftUI bug.
-  /// On iOS 27, the prominent tab keeps its selected styling after another tab is selected
-  /// if the tab bar was updated during its selection animation (e.g. item images being
-  /// reconfigured, or React re-rendering in response to the selection).
-  /// Re-assigning the prominent tab identifier makes UIKit rebuild the prominent tab button.
-  private func refreshProminentTab(tabBarController: UITabBarController?) {
-    #if compiler(>=6.4)
-      guard #available(iOS 27, *) else { return }
-
-      DispatchQueue.main.async { [weak tabBarController] in
-        guard let tabBarController,
-          let identifier = tabBarController.prominentTabIdentifier,
-          tabBarController.selectedTab?.identifier != identifier
-        else { return }
-
-        tabBarController.setProminentTabIdentifier(nil, animated: false)
-        tabBarController.setProminentTabIdentifier(identifier, animated: false)
-      }
-    #endif
-  }
-#endif
-
 #if !os(macOS)
   private func configureTransparentAppearance(tabBar: UITabBar, props: TabViewProps) {
     tabBar.barTintColor = props.barTintColor
@@ -251,70 +219,34 @@ struct TabViewImpl: View {
     }
   }
 
+  /// Configures the parts of the tab bar items that SwiftUI can't express.
+  ///
+  /// The unselected image is owned by SwiftUI through the tab label (see `TabBarItemImages.labelImage`),
+  /// so it's never assigned here. Assigning item images while the tab bar animates (e.g. minimizing or
+  /// switching tabs) breaks its selection styling on iOS 27, so `selectedImage` is only assigned when it
+  /// changes, and SwiftUI updates its images only when a label changes.
   private func configureTabBarItemImages(items: [UITabBarItem], props: TabViewProps) {
     for (tabBarIndex, item) in items.enumerated() {
-      guard let tabData = props.filteredItems[safe: tabBarIndex],
-        let itemIndex = props.items.firstIndex(where: { $0.key == tabData.key })
-      else { continue }
+      guard let tabData = props.filteredItems[safe: tabBarIndex] else { continue }
 
       let tabActiveColor = tabData.activeTintColor ?? props.activeTintColor
-      let assetIcon = props.icons[itemIndex]
-      let icon = assetIcon ?? makeSFSymbolImage(named: tabData.sfSymbol)
-      let focusedIcon =
-        props.focusedIcons[itemIndex] ?? makeSFSymbolImage(named: tabData.focusedSfSymbol) ?? icon
-      let preservesOriginalIconColors = preservesOriginalIconColors(tabData: tabData)
-      let useBakedTintColors = shouldUseExperimentalBakedTintColors(props: props)
-      let hasEffectiveRole: Bool
-      if #available(iOS 18, macOS 15, visionOS 2, tvOS 18, *) {
-        hasEffectiveRole = tabData.role?.convert() != nil
-      } else {
-        hasEffectiveRole = false
-      }
-      let shouldRenderLabelIntoImage =
-        props.hasCustomTintColors && props.labeled && !hasEffectiveRole && icon != nil
+      let images = props.itemImages.images(for: tabData, props: props)
 
       item.accessibilityLabel = tabData.title
 
-      if useBakedTintColors, shouldRenderLabelIntoImage, let icon {
-        let selectedIcon = focusedIcon ?? icon
+      if let images {
+        assignSelectedImage(images.selectedImage, to: item)
+      }
+
+      if images?.rendersLabelIntoImage == true {
         item.title = ""
         item.titlePositionAdjustment = UIOffset(horizontal: 0, vertical: 100)
-        item.image = makeTabBarItemImage(
-          icon: icon,
-          title: tabData.title,
-          color: props.inactiveTintColor,
-          preservesOriginalIconColors: preservesOriginalIconColors,
-          props: props
-        )
-        item.selectedImage = makeTabBarItemImage(
-          icon: selectedIcon,
-          title: tabData.title,
-          color: tabActiveColor,
-          preservesOriginalIconColors: preservesOriginalIconColors,
-          props: props
-        )
         continue
       }
 
       item.title = props.labeled ? tabData.title : nil
       item.titlePositionAdjustment = UIOffset(horizontal: 0, vertical: 0)
 
-      if let icon {
-        let selectedIcon = focusedIcon ?? icon
-        item.image = renderTabBarIcon(
-          icon,
-          color: props.inactiveTintColor,
-          preservesOriginalIconColors: preservesOriginalIconColors,
-          forceTintColor: useBakedTintColors
-        )
-        item.selectedImage = renderTabBarIcon(
-          selectedIcon,
-          color: tabActiveColor,
-          preservesOriginalIconColors: preservesOriginalIconColors,
-          forceTintColor: useBakedTintColors
-        )
-      }
-
       item.setTitleTextAttributes(
         TabBarFontSize.createFontAttributes(
           size: props.fontSize.map(CGFloat.init) ?? TabBarFontSize.defaultSize,
@@ -327,8 +259,147 @@ struct TabViewImpl: View {
     }
   }
 
-  private func preservesOriginalIconColors(tabData: TabInfo) -> Bool {
-    tabData.iconRenderingMode == "original"
+  private func assignSelectedImage(_ image: UIImage, to item: UITabBarItem) {
+    // `UITabBarItem.selectedImage` returns a copy, so compare against the last assigned instance instead.
+    let assignedImage = objc_getAssociatedObject(item, &AssociatedKeys.selectedImage) as? UIImage
+    guard assignedImage !== image else { return }
+
+    item.selectedImage = image
+    objc_setAssociatedObject(item, &AssociatedKeys.selectedImage, image, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)
+  }
+
+  private enum AssociatedKeys {
+    static var selectedImage: UInt8 = 0
+  }
+
+  struct TabBarItemImages {
+    /// Replaces the icon of the tab's SwiftUI label, or `nil` to keep the tab's own icon.
+    let labelImage: UIImage?
+    let selectedImage: UIImage
+    let rendersLabelIntoImage: Bool
+  }
+
+  final class TabBarItemImageCache {
+    private var entries: [String: (inputs: Inputs, images: TabBarItemImages?)] = [:]
+
+    func images(for tabData: TabInfo, props: TabViewProps) -> TabBarItemImages? {
+      guard let itemIndex = props.items.firstIndex(where: { $0.key == tabData.key }) else { return nil }
+
+      let assetIcon = props.icons[itemIndex]
+      let focusedAssetIcon = props.focusedIcons[itemIndex]
+      let useBakedTintColors = shouldUseExperimentalBakedTintColors(props: props)
+      let hasEffectiveRole: Bool
+      if #available(iOS 18, macOS 15, visionOS 2, tvOS 18, *) {
+        hasEffectiveRole = tabData.role?.convert() != nil
+      } else {
+        hasEffectiveRole = false
+      }
+      let inputs = Inputs(
+        icon: assetIcon.map(IconSource.image) ?? .sfSymbol(tabData.sfSymbol),
+        focusedIcon: focusedAssetIcon.map(IconSource.image) ?? tabData.focusedSfSymbol.map(IconSource.sfSymbol),
+        title: tabData.title,
+        inactiveTintColor: props.inactiveTintColor,
+        activeTintColor: tabData.activeTintColor ?? props.activeTintColor,
+        preservesOriginalIconColors: tabData.iconRenderingMode == "original",
+        useBakedTintColors: useBakedTintColors,
+        rendersLabelIntoImage: useBakedTintColors && props.hasCustomTintColors && props.labeled && !hasEffectiveRole,
+        fontSize: props.fontSize,
+        fontFamily: props.fontFamily,
+        fontWeight: props.fontWeight
+      )
+
+      if let entry = entries[tabData.key], entry.inputs == inputs {
+        return entry.images
+      }
+
+      let images = render(
+        icon: assetIcon ?? makeSFSymbolImage(named: tabData.sfSymbol),
+        focusedIcon: focusedAssetIcon ?? makeSFSymbolImage(named: tabData.focusedSfSymbol),
+        inputs: inputs,
+        props: props
+      )
+      entries[tabData.key] = (inputs, images)
+      return images
+    }
+
+    private func render(
+      icon: UIImage?,
+      focusedIcon: UIImage?,
+      inputs: Inputs,
+      props: TabViewProps
+    ) -> TabBarItemImages? {
+      guard let icon else { return nil }
+      let selectedIcon = focusedIcon ?? icon
+
+      if inputs.rendersLabelIntoImage {
+        return TabBarItemImages(
+          labelImage: makeTabBarItemImage(
+            icon: icon,
+            title: inputs.title,
+            color: inputs.inactiveTintColor,
+            preservesOriginalIconColors: inputs.preservesOriginalIconColors,
+            props: props
+          ),
+          selectedImage: makeTabBarItemImage(
+            icon: selectedIcon,
+            title: inputs.title,
+            color: inputs.activeTintColor,
+            preservesOriginalIconColors: inputs.preservesOriginalIconColors,
+            props: props
+          ),
+          rendersLabelIntoImage: true
+        )
+      }
+
+      return TabBarItemImages(
+        // Without baked tint colors, the tab's own icon is already what the label shows.
+        labelImage: inputs.useBakedTintColors
+          ? renderTabBarIcon(
+            icon,
+            color: inputs.inactiveTintColor,
+            preservesOriginalIconColors: inputs.preservesOriginalIconColors,
+            forceTintColor: true
+          )
+          : nil,
+        selectedImage: renderTabBarIcon(
+          selectedIcon,
+          color: inputs.activeTintColor,
+          preservesOriginalIconColors: inputs.preservesOriginalIconColors,
+          forceTintColor: inputs.useBakedTintColors
+        ),
+        rendersLabelIntoImage: false
+      )
+    }
+
+    private enum IconSource: Equatable {
+      case image(UIImage)
+      case sfSymbol(String)
+
+      static func == (lhs: IconSource, rhs: IconSource) -> Bool {
+        switch (lhs, rhs) {
+        case let (.image(lhs), .image(rhs)):
+          return lhs === rhs
+        case let (.sfSymbol(lhs), .sfSymbol(rhs)):
+          return lhs == rhs
+        default:
+          return false
+        }
+      }
+    }
+
+    private struct Inputs: Equatable {
+      let icon: IconSource
+      let focusedIcon: IconSource?
+      let title: String
+      let inactiveTintColor: UIColor?
+      let activeTintColor: UIColor?
+      let preservesOriginalIconColors: Bool
+      let useBakedTintColors: Bool
+      let rendersLabelIntoImage: Bool
+      let fontSize: Int?
+      let fontFamily: String?
+      let fontWeight: String?
+    }
   }
 
   private func renderTabBarIcon(
diff --git a/packages/react-native-bottom-tabs/ios/TabViewProps.swift b/packages/react-native-bottom-tabs/ios/TabViewProps.swift
index 19e2290e..d3453f57 100644
--- a/packages/react-native-bottom-tabs/ios/TabViewProps.swift
+++ b/packages/react-native-bottom-tabs/ios/TabViewProps.swift
@@ -83,6 +83,9 @@ class TabViewProps: ObservableObject {
   @Published var fontFamily: String?
   @Published var fontWeight: String?
   @Published var tabBarHidden: Bool = false
+  #if !os(macOS)
+    let itemImages = TabBarItemImageCache()
+  #endif
 
   var selectedActiveTintColor: PlatformColor? {
     if let selectedPage,

From 477432f413aeb97c7597f8b6306ff425975a661d Mon Sep 17 00:00:00 2001
From: Thiago Brezinski <thiagobrez@gmail.com>
Date: Thu, 24 Sep 2026 14:17:54 +0100
Subject: [PATCH 7/7] docs: clarify iOS tab role availability

---
 docs/docs/docs/guides/standalone-usage.mdx            | 2 +-
 docs/docs/docs/guides/usage-with-react-navigation.mdx | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/docs/docs/guides/standalone-usage.mdx b/docs/docs/docs/guides/standalone-usage.mdx
index d9f02c43..29c06bde 100644
--- a/docs/docs/docs/guides/standalone-usage.mdx
+++ b/docs/docs/docs/guides/standalone-usage.mdx
@@ -241,7 +241,7 @@ Each route in the `routes` array can have the following properties:
 - `activeTintColor`: Custom active tint color for this specific tab
 - `lazy`: Whether to lazy load this tab's content
 - `freezeOnBlur`: Whether to freeze the tab's content when it's not visible
-- `role`: A value that defines the purpose of the tab
+- `role`: A value that defines the purpose of the tab on iOS: `'search'` (iOS 18+) or `'prominent'` (iOS 27+, displayed as a regular tab on earlier versions)
 - `style`: Style object for the component wrapping the screen content
 - `preventsDefault`: Whether to prevent default tab switching behavior when pressed
 
diff --git a/docs/docs/docs/guides/usage-with-react-navigation.mdx b/docs/docs/docs/guides/usage-with-react-navigation.mdx
index 2622b962..8ff246ac 100644
--- a/docs/docs/docs/guides/usage-with-react-navigation.mdx
+++ b/docs/docs/docs/guides/usage-with-react-navigation.mdx
@@ -398,12 +398,12 @@ Test ID for the tab item. This can be used to find the tab item in the native vi
 
 #### `role` <Badge text="iOS 18+" type="info" />
 
-A value that defines the purpose of the tab. This can be used to pin and separate search tabs
+A value that defines the purpose of the tab.
 
 Available options:
 
-- `search` - The search role.
-- `prominent` - Mark one tab as visually more important than the others (`SDK 27+`).
+- `search` - Marks the tab as the search tab, which the system can pin to the trailing end of the tab bar. On iOS 27+, it may also receive the prominent treatment when no tab has the `prominent` role.
+- `prominent` <Badge text="iOS 27+" type="info" /> - Gives the tab more visual emphasis than the others. Only one tab can be prominent. Requires building with the iOS 27 SDK, and on earlier iOS versions the tab is displayed as a regular tab.
 
 #### `sceneStyle`