react-native-screens 5.0.0-alpha.3 → 5.0.0-alpha.4

package/src/components/stack/header/ios/StackHeaderItem.ios.tsx

@@ -6,7 +6,7 @@ import { NativeSyntheticEvent, StyleSheet } from 'react-native';
 import { resolveIconAssetSources, resolveMenuIcons } from './iconUtils.ios';
 
 export default function StackHeaderItem(props: StackHeaderItemProps) {
-  const { render, onPress, icon, menu, ...rest } = props;
+  const { render, onPress, icon, menu, menuRepresentation, ...rest } = props;
 
   // `rest.menu` includes some JS callback within nested menu specification
   // codegen strips JS functions and replaces them with NULLT and keys of such type
@@ -24,12 +24,20 @@ export default function StackHeaderItem(props: StackHeaderItemProps) {
     () => (menu != null ? resolveMenuIcons(menu) : undefined),
     [menu],
   );
+  const resolvedMenuRepresentation = useMemo(
+    () =>
+      menuRepresentation != null
+        ? resolveMenuIcons(menuRepresentation)
+        : undefined,
+    [menuRepresentation],
+  );
 
   return (
     <StackHeaderItemIOSNativeComponent
       {...rest}
       icon={resolvedIcon}
       menu={resolvedMenu}
+      menuRepresentation={resolvedMenuRepresentation}
       // We need to tell iOS that we want the handler to be attached only when we actually require it
       // because doing so makes the menu appear on long press instead of tap
       respondsToOnPress={!!onPress}

package/src/components/stack/header/ios/StackHeaderItem.ios.types.ts

@@ -1,6 +1,7 @@
 import type { ReactElement } from 'react';
 import type { PlatformIconIOS } from '../../../shared/types';
 import type { StackHeaderMenuIOS } from './StackHeaderMenu.ios.types';
+import type { StackHeaderItemVisibilityPriorityIOS } from '../StackHeaderConfig.ios.types';
 
 export type StackHeaderItemPlacement =
   | 'leading'
@@ -14,9 +15,13 @@ export type StackHeaderItemProps = {
   itemId?: string | undefined;
   identifier?: string | undefined;
   hidesSharedBackground?: boolean | undefined;
+  visibilityPriority?: StackHeaderItemVisibilityPriorityIOS | undefined;
   title?: string | undefined;
   icon?: PlatformIconIOS | undefined;
   render?: (() => ReactElement) | undefined;
   menu?: StackHeaderMenuIOS | undefined;
+  menuRepresentation?: StackHeaderMenuIOS | undefined;
+  variant?: 'plain' | 'prominent' | undefined;
+  disabled?: boolean | undefined;
   onPress?: (() => void) | undefined;
 };

package/src/components/stack/host/StackHost.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { StyleSheet } from 'react-native';
+import { Platform, StyleSheet } from 'react-native';
 import StackHostNativeComponent from '../../../fabric/stack/StackHostNativeComponent';
 import type { StackHostProps } from './StackHost.types';
 
@@ -7,10 +7,17 @@ import type { StackHostProps } from './StackHost.types';
  * EXPERIMENTAL API, MIGHT CHANGE W/O ANY NOTICE
  */
 function StackHost(props: StackHostProps) {
-  const { children, ref, ...restProps } = props;
+  const { children, ref, direction, ...restProps } = props;
+
+  // RN's `direction` style sets the native View's layoutDirection, which the
+  // stack's native subtree inherits. iOS needs a trait override instead.
+  const directionStyle = Platform.OS === 'android' ? { direction } : undefined;
 
   return (
-    <StackHostNativeComponent ref={ref} style={styles.container} {...restProps}>
+    <StackHostNativeComponent
+      ref={ref}
+      style={[styles.container, directionStyle]}
+      {...restProps}>
       {children}
     </StackHostNativeComponent>
   );

package/src/components/stack/host/StackHost.types.ts

@@ -1,10 +1,12 @@
 import React from 'react';
 import type { HostInstance, ViewProps } from 'react-native';
 import { type NativeProps } from '../../../fabric/stack/StackHostNativeComponent';
-import type { ColorScheme } from '../../shared/types';
+import type { ColorScheme, Direction } from '../../shared/types';
 
 export type StackHostColorScheme = ColorScheme | 'inherit';
 
+export type StackHostDirection = Direction | 'inherit';
+
 export type StackHostProps = {
   // General
   children: NonNullable<ViewProps['children']>;
@@ -12,6 +14,28 @@ export type StackHostProps = {
   ref?:
     | React.RefObject<(React.Component<NativeProps> & HostInstance) | null>
     | undefined;
+  /**
+   * @summary Specifies the layout direction of the native container, its views
+   * and child containers.
+   *
+   * The following values are currently supported:
+   * - `inherit` - uses parent's layout direction,
+   * - `ltr` - forces left-to-right layout direction,
+   * - `rtl` - forces right-to-left layout direction.
+   *
+   * @remarks
+   * Layout direction isn't currently supported on iOS.
+   *
+   * On Android, this property relies on `react-native`'s `style.direction`
+   * (which sets the native Android `layoutDirection` View property). It is
+   * propagated via the view hierarchy, so `inherit` falls back to the direction
+   * set on one of the parent views.
+   *
+   * @default inherit
+   *
+   * @platform android
+   */
+  direction?: StackHostDirection | undefined;
   /**
    * @summary Specifies the color scheme used by the container and any child
    * containers.

package/src/components/stack/host/StackHost.web.tsx

@@ -1,7 +1,4 @@
-import { View, ViewProps } from 'react-native';
-
-// TODO: Determine what this type is & whether it should not be removed
-export type ScreenStackNativeProps = ViewProps;
+import { View } from 'react-native';
 
 const StackHost = View;
 

package/src/components/stack/index.ts

@@ -2,7 +2,11 @@ import { StackHost } from './host';
 import { StackScreen } from './screen';
 import { StackHeaderConfig } from './header';
 
-export type { StackHostProps, StackHostColorScheme } from './host';
+export type {
+  StackHostProps,
+  StackHostColorScheme,
+  StackHostDirection,
+} from './host';
 
 export type {
   OnDismissEventPayload,
@@ -39,8 +43,12 @@ export type {
   StackHeaderToolbarMenuItemTypeAndroid,
   // iOS
   StackHeaderBackButtonDisplayModeIOS,
+  StackHeaderMinimizationBehaviorIOS,
+  StackHeaderRestorationBehaviorIOS,
+  StackHeaderItemVisibilityPriorityIOS,
   StackHeaderConfigPropsIOS,
   StackHeaderAppearanceIOS,
+  StackHeaderItemVariantIOS,
   StackHeaderInlineItemIOS,
   StackHeaderInlineCustomItemIOS,
   StackHeaderTitleCustomItemIOS,

package/src/components/tabs/host/TabsHost.ios.tsx

@@ -50,9 +50,11 @@ function TabsHost(props: TabsHostProps) {
       layoutDirection={direction}
       tabBarHiddenAnimationEnabled={ios?.tabBarHiddenAnimationEnabled}
       tabBarControllerMode={ios?.tabBarControllerMode}
+      tabBarSidebarPreferredPlacement={ios?.tabBarSidebarPreferredPlacement}
       tabBarMinimizeBehavior={ios?.tabBarMinimizeBehavior}
       tabBarTintColor={ios?.tabBarTintColor}
       bottomAccessoryHidden={ios?.bottomAccessoryHidden}
+      prominentScreenKey={ios?.prominentScreenKey}
       onMoreTabSelected={ios?.onMoreTabSelected}>
       {children}
       {ios?.bottomAccessory && isIOS26OrHigher && (

package/src/components/tabs/host/TabsHost.ios.types.ts

@@ -33,6 +33,11 @@ export type TabBarMinimizeBehavior =
 
 export type TabBarControllerMode = 'automatic' | 'tabBar' | 'tabSidebar';
 
+export type TabBarSidebarPreferredPlacement =
+  | 'automatic'
+  | 'sidebar'
+  | 'tabBar';
+
 export interface TabsHostPropsIOS {
   /**
    * @summary Whether changes of `tabBarHidden` are animated.
@@ -141,6 +146,61 @@ export interface TabsHostPropsIOS {
    * @supported iOS 18 or higher
    */
   tabBarControllerMode?: TabBarControllerMode | undefined;
+  /**
+   * @summary Specifies whether the sidebar or the tab bar is preferred when only
+   * one of them can be displayed.
+   *
+   * @description
+   * The following values are currently supported:
+   *
+   * - `automatic` - the system resolves to the platform default (the tab bar on iOS)
+   * - `sidebar` - the sidebar is displayed when it is available
+   * - `tabBar` - the tab bar is displayed
+   *
+   * This prop requires `tabBarControllerMode` to be set to `tabSidebar`.
+   * Otherwise, the sidebar is not considered a supported mode and the tab bar
+   * is always displayed.
+   *
+   * The button that shows the sidebar is visible only when the screen has
+   * a header. After using it, the sidebar is displayed and the content is accessible.
+   *
+   * The sidebar can also be shown with a swipe from the leading edge.
+   * In this case, the sidebar overlaps the content, and the content is not accessible until
+   * the sidebar is hidden.
+   *
+   * The sidebar is enabled only when the interface has a regular
+   * horizontal size class. On iPhone, this applies only to larger models
+   * (e.g. Pro Max, Plus and Air) in landscape orientation. On other iPhones
+   * (e.g. iPhone 18 Pro), and on all iPhones in portrait orientation,
+   * the tab bar is always displayed.
+   *
+   * @default Defaults to `automatic`.
+   *
+   * Not supported on tvOS.
+   *
+   * @platform ios
+   * @supported iOS 27 or higher
+   */
+  tabBarSidebarPreferredPlacement?: TabBarSidebarPreferredPlacement | undefined;
+  /**
+   * @summary `screenKey` of the tab screen that should receive the prominent treatment.
+   *
+   * Must match the `screenKey` of one of the child `TabsScreen`s. Where supported, that tab
+   * receives enhanced visual emphasis in the tab bar - it is detached from the other items
+   * onto its own surface and stays visible when the tab bar minimizes on scroll
+   * (see `tabBarMinimizeBehavior`).
+   *
+   * When omitted, a tab with `role: 'search'` and `automaticallyActivatesSearch` enabled
+   * becomes prominent automatically, otherwise no tab is prominent.
+   *
+   * @see {@link https://developer.apple.com/documentation/uikit/uitabbarcontroller/prominenttabidentifier|UITabBarController.prominentTabIdentifier}
+   *
+   * Not supported on tvOS.
+   *
+   * @platform ios
+   * @supported iOS 27 or higher
+   */
+  prominentScreenKey?: string | undefined;
   /**
    * @summary
    * A callback that gets invoked when the user taps the "More" tab bar item.

package/src/components/tabs/host/TabsHost.tsx

@@ -0,0 +1,7 @@
+import React from 'react';
+import { View } from 'react-native';
+import type { TabsHostProps } from './TabsHost.types';
+
+const TabsHost: React.ComponentType<TabsHostProps> = View;
+
+export default TabsHost;

package/src/components/tabs/index.ts

@@ -19,6 +19,7 @@ export type {
   TabsBottomAccessoryComponentFactory,
   TabBarMinimizeBehavior,
   TabBarControllerMode,
+  TabBarSidebarPreferredPlacement,
   TabsHostPropsIOS,
 } from './host';
 
@@ -28,12 +29,20 @@ export type {
   TabsScreenPropsBase,
   TabsScreenProps,
   // Android
+  TabsScreenIconAndroid,
+  TabsScreenIconTintingAndroid,
   TabBarItemLabelVisibilityMode,
   TabsScreenItemStateAppearanceAndroid,
   TabsScreenAppearanceAndroid,
   TabsScreenPropsAndroid,
   // iOS
+  TabsScreenIconIOS,
+  TabsScreenIconImageRenderingModeIOS,
+  TabsScreenIconSymbolRenderingModeIOS,
+  TabsScreenIconTemplateIOS,
+  TabsScreenIconXcassetIOS,
   TabsScreenBlurEffect,
+  TabsScreenRole,
   TabsScreenSystemItem,
   TabsScreenAppearanceIOS,
   TabsScreenItemAppearanceIOS,

package/src/components/tabs/screen/TabsScreen.android.tsx

@@ -8,6 +8,7 @@ import {
 } from 'react-native';
 import TabsScreenAndroidNativeComponent, {
   type Appearance,
+  type IconTinting,
   type ItemStateAppearance,
   type NativeProps as TabsScreenAndroidNativeComponentProps,
 } from '../../../fabric/tabs/TabsScreenAndroidNativeComponent';
@@ -16,7 +17,7 @@ import type {
   TabsScreenItemStateAppearanceAndroid,
 } from './TabsScreen.android.types';
 import type { TabsScreenProps } from '../screen/TabsScreen.types';
-import type { PlatformIconAndroid } from '../../shared/types';
+import type { TabsScreenIconAndroid } from './TabsScreenIcon.types';
 import { useTabsScreen } from './useTabsScreen';
 import { parseAndroidIconToNativeProps } from '../../shared';
 
@@ -128,13 +129,15 @@ function mapItemStateAppearanceToNativeProp(
 }
 
 function parseIconsToNativeProps(
-  icon: PlatformIconAndroid | undefined,
-  selectedIcon: PlatformIconAndroid | undefined,
+  icon: TabsScreenIconAndroid | undefined,
+  selectedIcon: TabsScreenIconAndroid | undefined,
 ): {
   imageIconResource?: ImageResolvedAssetSource | undefined;
   drawableIconResourceName?: string | undefined;
+  iconTinting?: IconTinting | undefined;
   selectedImageIconResource?: ImageResolvedAssetSource | undefined;
   selectedDrawableIconResourceName?: string | undefined;
+  selectedIconTinting?: IconTinting | undefined;
 } {
   const parsedIcon = parseAndroidIconToNativeProps(icon);
   const parsedSelectedIcon = parseAndroidIconToNativeProps(selectedIcon);
@@ -142,9 +145,11 @@ function parseIconsToNativeProps(
   return {
     imageIconResource: parsedIcon.imageIconResource,
     drawableIconResourceName: parsedIcon.drawableIconResourceName,
+    iconTinting: icon?.tinting,
     selectedImageIconResource: parsedSelectedIcon.imageIconResource,
     selectedDrawableIconResourceName:
       parsedSelectedIcon.drawableIconResourceName,
+    selectedIconTinting: selectedIcon?.tinting,
   };
 }
 

package/src/components/tabs/screen/TabsScreen.android.types.ts

@@ -1,5 +1,5 @@
 import type { ColorValue, TextStyle } from 'react-native';
-import type { PlatformIconAndroid } from '../../shared/types';
+import type { TabsScreenIconAndroid } from './TabsScreenIcon.types';
 
 export type TabBarItemLabelVisibilityMode =
   | 'auto'
@@ -85,6 +85,14 @@ export interface TabsScreenAppearanceAndroid {
    * @platform android
    */
   disabled?: TabsScreenItemStateAppearanceAndroid | undefined;
+  /**
+   * @summary Specifies the icon size of this tab's item in dp.
+   *
+   * Applies to this tab only. Unset uses the system default.
+   *
+   * @platform android
+   */
+  tabBarItemIconSize?: number | undefined;
   /**
    * @summary Specifies the background color of the active indicator.
    *
@@ -99,6 +107,24 @@ export interface TabsScreenAppearanceAndroid {
    * @platform android
    */
   tabBarItemActiveIndicatorEnabled?: boolean | undefined;
+  /**
+   * @summary Specifies the width of this tab's active indicator in dp.
+   *
+   * Applies to this tab only. If unset, it is this tab's icon size plus the
+   * default Material padding.
+   *
+   * @platform android
+   */
+  tabBarItemActiveIndicatorWidth?: number | undefined;
+  /**
+   * @summary Specifies the height of this tab's active indicator in dp.
+   *
+   * Applies to this tab only. If unset, it is this tab's icon size plus the
+   * default Material padding.
+   *
+   * @platform android
+   */
+  tabBarItemActiveIndicatorHeight?: number | undefined;
   /**
    * @summary Specifies the font family used for the title of each tab bar item.
    *
@@ -162,28 +188,37 @@ export interface TabsScreenPropsAndroid {
    * @summary Specifies the icon for the tab bar item.
    *
    * Supported values:
-   * - `{ type: 'imageSource', imageSource }`
-   *   Uses an image from the provided resource.
+   * - `{ type: 'imageSource', imageSource, tinting? }`
+   *   Uses an image from the provided resource. `tinting` defaults to
+   *   `default`: the tab bar tints the image with the item icon color.
+   *   `original` keeps the image's own colors.
    *
    *   Remarks: `imageSource` type doesn't support SVGs on Android.
    *   For loading SVGs use `drawableResource` type.
    *
-   * - `{ type: 'drawableResource', name }`
-   *   Uses a drawable resource with the given name.
+   * - `{ type: 'drawableResource', name, tinting? }`
+   *   Uses a drawable resource with the given name. `tinting` defaults to
+   *   `default`: the tab bar tints the drawable with the item icon color.
+   *   `original` keeps the drawable's own colors, e.g. of a multicolor
+   *   VectorDrawable.
    *
    *   Remarks: Requires passing a drawable to resources via Android Studio.
    *
+   * See `TabsScreenIconTintingAndroid` for the meaning of each value.
+   *
    * @platform android
    */
-  icon?: PlatformIconAndroid | undefined;
+  icon?: TabsScreenIconAndroid | undefined;
   /**
    * @summary Specifies the icon for tab bar item when it is selected.
    *
    * Supports the same values as `icon` property for given platform.
+   * `tinting` may differ from the one of `icon`, e.g. a drawable that is
+   * tinted while unselected and shows its own colors while selected.
    *
    * To use `selectedIcon`, `icon` must also be provided.
    *
    * @platform android
    */
-  selectedIcon?: PlatformIconAndroid | undefined;
+  selectedIcon?: TabsScreenIconAndroid | undefined;
 }

package/src/components/tabs/screen/TabsScreen.ios.tsx

@@ -9,6 +9,8 @@ import {
 } from 'react-native';
 import TabsScreenIOSNativeComponent, {
   type IconType,
+  type IconImageRenderingMode,
+  type IconSymbolRenderingMode,
   type NativeProps as TabsScreenIOSNativeComponentProps,
   type Appearance,
   type ItemAppearance,
@@ -20,7 +22,7 @@ import type {
   TabsScreenItemStateAppearanceIOS,
 } from './TabsScreen.ios.types';
 import type { TabsScreenProps } from './TabsScreen.types';
-import type { PlatformIconIOS } from '../../shared/types';
+import type { TabsScreenIconIOS } from './TabsScreenIcon.types';
 import { useTabsScreen } from './useTabsScreen';
 
 function TabsScreen(props: TabsScreenProps) {
@@ -72,6 +74,8 @@ function TabsScreen(props: TabsScreenProps) {
       )}
       userInterfaceStyle={ios?.experimental_userInterfaceStyle}
       systemItem={ios?.systemItem}
+      tabRole={ios?.role}
+      automaticallyActivatesSearch={ios?.automaticallyActivatesSearch}
       overrideScrollViewContentInsetAdjustmentBehavior={
         ios?.overrideScrollViewContentInsetAdjustmentBehavior
       }>
@@ -146,14 +150,18 @@ function mapItemStateAppearanceToNativeProp(
 }
 
 function parseIconsToNativeProps(
-  icon: PlatformIconIOS | undefined,
-  selectedIcon: PlatformIconIOS | undefined,
+  icon: TabsScreenIconIOS | undefined,
+  selectedIcon: TabsScreenIconIOS | undefined,
 ): {
   imageIconResource?: ImageResolvedAssetSource | undefined;
   drawableIconResourceName?: string | undefined;
   iconType?: IconType | undefined;
+  iconImageRenderingMode?: IconImageRenderingMode | undefined;
+  iconSymbolRenderingMode?: IconSymbolRenderingMode | undefined;
   iconImageSource?: ImageSourcePropType | undefined;
   iconResourceName?: string | undefined;
+  selectedIconImageRenderingMode?: IconImageRenderingMode | undefined;
+  selectedIconSymbolRenderingMode?: IconSymbolRenderingMode | undefined;
   selectedIconImageSource?: ImageSourcePropType | undefined;
   selectedIconResourceName?: string | undefined;
 } {
@@ -177,15 +185,21 @@ function parseIconsToNativeProps(
 
   return {
     iconType: parsedIcon.iconType,
+    iconImageRenderingMode: parsedIcon.iconImageRenderingMode,
+    iconSymbolRenderingMode: parsedIcon.iconSymbolRenderingMode,
     iconImageSource: parsedIcon.iconImageSource,
     iconResourceName: parsedIcon.iconResourceName,
+    selectedIconImageRenderingMode: parsedSelectedIcon.iconImageRenderingMode,
+    selectedIconSymbolRenderingMode: parsedSelectedIcon.iconSymbolRenderingMode,
     selectedIconImageSource: parsedSelectedIcon.iconImageSource,
     selectedIconResourceName: parsedSelectedIcon.iconResourceName,
   };
 }
 
-function parseIconToNativeProps(icon: PlatformIconIOS | undefined): {
+function parseIconToNativeProps(icon: TabsScreenIconIOS | undefined): {
   iconType?: IconType | undefined;
+  iconImageRenderingMode?: IconImageRenderingMode | undefined;
+  iconSymbolRenderingMode?: IconSymbolRenderingMode | undefined;
   iconImageSource?: ImageSourcePropType | undefined;
   iconResourceName?: string | undefined;
 } {
@@ -196,16 +210,19 @@ function parseIconToNativeProps(icon: PlatformIconIOS | undefined): {
   if (icon.type === 'sfSymbol') {
     return {
       iconType: 'sfSymbol',
+      iconSymbolRenderingMode: icon.renderingMode,
       iconResourceName: icon.name,
     };
   } else if (icon.type === 'imageSource') {
     return {
       iconType: 'image',
+      iconImageRenderingMode: icon.renderingMode,
       iconImageSource: icon.imageSource,
     };
   } else if (icon.type === 'templateSource') {
     return {
-      iconType: 'template',
+      iconType: 'image',
+      iconImageRenderingMode: 'template',
       iconImageSource: icon.templateSource,
     };
   } else if (icon.type === 'xcasset') {

package/src/components/tabs/screen/TabsScreen.ios.types.ts

@@ -1,12 +1,11 @@
 import type { ColorValue, TextStyle } from 'react-native';
-import type {
-  UserInterfaceStyle,
-  BlurEffect,
-  PlatformIconIOS,
-} from '../../shared/types';
+import type { UserInterfaceStyle, BlurEffect } from '../../shared/types';
+import type { TabsScreenIconIOS } from './TabsScreenIcon.types';
 
 export type TabsScreenBlurEffect = BlurEffect | 'systemDefault';
 
+export type TabsScreenRole = 'search';
+
 export type TabsScreenSystemItem =
   | 'bookmarks'
   | 'contacts'
@@ -233,33 +232,52 @@ export interface TabsScreenPropsIOS {
    * @summary Specifies the icon for the tab bar item.
    *
    * Supported values:
-   * - `{ type: 'imageSource', imageSource }`
-   *   Uses an image from the provided resource.
-   * - `{ type: 'sfSymbol', name }`
-   *   Uses an SF Symbol with the specified name.
+   * - `{ type: 'imageSource', imageSource, renderingMode? }`
+   *   Uses an image from the provided resource. `renderingMode` defaults to
+   *   `default`, which keeps the image's own colors. With `template` it is
+   *   used as a template image and follows the state-dependent icon color.
+   * - `{ type: 'sfSymbol', name, renderingMode? }`
+   *   Uses an SF Symbol with the specified name. If no system symbol
+   *   matches, falls back to a custom symbol with that name from the app's
+   *   asset catalog. `renderingMode` defaults to `default`, the system
+   *   behavior: a single color for system symbols, while for custom symbols
+   *   the rendering intent set in the asset catalog may change it. `original`
+   *   shows the symbol's own color layers (Apple's "multicolor" rendering).
    * - `{ type: 'xcasset', name }`
-   *   Uses asset from Xcassets.
+   *   Deprecated: use `sfSymbol` for custom symbols from the asset catalog, or
+   *   `imageSource` with `{ uri: 'name' }` for asset catalog images (append
+   *   `.png` to names containing a dot; add `renderingMode: 'template'` for an
+   *   asset whose "Render As" is not `Original Image`).
+   *   Uses an image from the asset catalog. Its colors follow the asset's
+   *   "Render As" setting in the catalog: `Original Image` keeps its own colors,
+   *   `Default` and `Template Image` follow the state-dependent icon color.
    * - `{ type: 'templateSource', templateSource }`
-   *   Uses the provided image as a template image.
-   *   The icon color will depend on the current state
-   *   of the tab bar item and icon color-related props.
+   *   Deprecated: use `{ type: 'imageSource', imageSource, renderingMode: 'template' }`
+   *   instead. Uses the provided image as a template image.
+   *
+   * See `TabsScreenIconImageRenderingModeIOS` and
+   * `TabsScreenIconSymbolRenderingModeIOS` for the meaning of each rendering mode.
    *
    * If no `selectedIcon` is provided, this icon will also
    * be used as the selected state icon.
    *
    * @platform ios
    */
-  icon?: PlatformIconIOS | undefined;
+  icon?: TabsScreenIconIOS | undefined;
   /**
    * @summary Specifies the icon for tab bar item when it is selected.
    *
-   * Supports the same values as `icon` property.
+   * Supports the same values as `icon` property. It must use the same icon
+   * `type` as `icon`; `renderingMode` may differ, e.g.
+   * `icon: { type: 'sfSymbol', name }` with
+   * `selectedIcon: { type: 'sfSymbol', name, renderingMode: 'original' }`
+   * shows the symbol tinted while unselected and in its own colors while selected.
    *
    * To use `selectedIcon`, `icon` must also be provided.
    *
    * @platform ios
    */
-  selectedIcon?: PlatformIconIOS | undefined;
+  selectedIcon?: TabsScreenIconIOS | undefined;
   /**
    * @summary System-provided tab bar item with predefined icon and title
    *
@@ -269,13 +287,57 @@ export interface TabsScreenPropsIOS {
    * overridden by providing a custom `title`.
    *
    * @remarks
-   * On iOS 26, `systemItem: 'search'` acts as a detached tab bar item, which does not display any title (system or custom).
+   * On iOS 26, `systemItem: 'search'` acts as a detached tab bar item, which does not display
+   * any title (system or custom). This no longer applies on iOS 27; to get a similar separation
+   * use `role: 'search'` together with `automaticallyActivatesSearch`.
    *
    * @see {@link https://developer.apple.com/documentation/uikit/uitabbaritem/systemitem|UITabBarItem.SystemItem}
    *
    * @platform ios
    */
   systemItem?: TabsScreenSystemItem | undefined;
+  /**
+   * @summary Gives this tab a system role. Currently the only role is `'search'`,
+   * which marks the tab as the system search tab.
+   *
+   * On iOS 26.1+ (where tabs are managed through the `UITab` API) a tab screen with
+   * `role: 'search'` is backed natively by `UISearchTab`, which enables the system
+   * search behavior: `automaticallyActivatesSearch` and the detached trailing
+   * placement UIKit gives search tabs. Behavior differs between OS versions: iOS 26.x
+   * detaches `UISearchTab` unconditionally, iOS 27.0 only while `automaticallyActivatesSearch`
+   * is enabled. This prop does not affect the tab bar item's icon or title - combine
+   * it with `systemItem: 'search'` for the system magnifier item. On iOS 27+ the detached
+   * (prominent) placement can be given to any tab instead through `TabsHost`
+   * `ios.prominentScreenKey`.
+   *
+   * The native tab class cannot change during the screen's lifetime - changing
+   * `role` on a mounted tab screen is not supported and triggers an assertion
+   * in development builds.
+   *
+   * @see {@link https://developer.apple.com/documentation/uikit/uisearchtab|UISearchTab}
+   *
+   * @default undefined
+   *
+   * @platform ios
+   * @supported iOS 26.1 or higher
+   */
+  role?: TabsScreenRole | undefined;
+  /**
+   * @summary Specifies whether selecting this tab automatically activates its search field.
+   *
+   * Effective only for tab screens with `role: 'search'` and only when a search bar
+   * is configured in the header of the screen stack nested in this tab
+   * (see `headerSearchBarOptions`). When enabled, selecting the search tab immediately
+   * activates the search field. Cancelling the search restores the previously selected tab.
+   *
+   * @see {@link https://developer.apple.com/documentation/uikit/uisearchtab/automaticallyactivatessearch|UISearchTab.automaticallyActivatesSearch}
+   *
+   * @default false
+   *
+   * @platform ios
+   * @supported iOS 26.1 or higher
+   */
+  automaticallyActivatesSearch?: boolean | undefined;
   /**
    * @summary Specifies if `contentInsetAdjustmentBehavior` of first ScrollView
    * in first descendant chain from tab screen should be overridden back from `never`

package/src/components/tabs/screen/TabsScreen.tsx

@@ -0,0 +1,7 @@
+import React from 'react';
+import { View } from 'react-native';
+import type { TabsScreenProps } from './TabsScreen.types';
+
+const TabsScreen: React.ComponentType<TabsScreenProps> = View;
+
+export default TabsScreen;