@react-navigation/native-stack 8.0.0-alpha.4 → 8.0.0-alpha.40

package/lib/typescript/src/types.d.ts

@@ -1,7 +1,8 @@
+import type { Icon } from '@react-navigation/elements';
 import type { DefaultNavigatorOptions, Descriptor, NavigationHelpers, NavigationProp, ParamListBase, Route, RouteProp, StackActionHelpers, StackNavigationState, StackRouterOptions, Theme } from '@react-navigation/native';
-import type { ColorValue, ImageSourcePropType, StyleProp, TextStyle, ViewStyle } from 'react-native';
+import * as React from 'react';
+import type { ColorValue, StyleProp, TextStyle, ViewStyle } from 'react-native';
 import type { ScreenProps, ScreenStackHeaderConfigProps, ScrollEdgeEffect, SearchBarProps } from 'react-native-screens';
-import type { SFSymbol } from 'sf-symbols-typescript';
 export type NativeStackNavigationEventMap = {
     /**
      * Event which fires when a transition animation starts.
@@ -63,7 +64,7 @@ export type NativeStackHeaderProps = {
          * The `href` to use for the anchor tag on web
          */
         href: string | undefined;
-    };
+    } | undefined;
     /**
      * Options for the current screen.
      */
@@ -81,22 +82,22 @@ export type NativeStackHeaderItemProps = {
     /**
      * Tint color for the header.
      */
-    tintColor?: ColorValue;
+    tintColor?: ColorValue | undefined;
     /**
      * Whether it's possible to navigate back in stack.
      */
-    canGoBack?: boolean;
+    canGoBack?: boolean | undefined;
 };
 export type NativeStackHeaderBackProps = NativeStackHeaderItemProps & {
     /**
      * Label text for the button. Usually the title of the previous screen.
      * By default, this is only shown on iOS 18.
      */
-    label?: string;
+    label?: string | undefined;
     /**
      * The `href` to use for the anchor tag on web
      */
-    href?: string;
+    href?: string | undefined;
 };
 /**
  * @deprecated Use `NativeStackHeaderBackProps` instead.
@@ -110,18 +111,18 @@ export type NativeStackNavigationOptions = {
     /**
      * String that can be displayed in the header as a fallback for `headerTitle`.
      */
-    title?: string;
+    title?: string | undefined;
     /**
      * Function that given `HeaderProps` returns a React Element to display as a header.
      */
-    header?: (props: NativeStackHeaderProps) => React.ReactNode;
+    header?: ((props: NativeStackHeaderProps) => React.ReactNode) | undefined;
     /**
      * Whether the back button is visible in the header.
      * You can use it to show a back button alongside `headerLeft` if you have specified it.
      *
      * This will have no effect on the first screen in the stack.
      */
-    headerBackVisible?: boolean;
+    headerBackVisible?: boolean | undefined;
     /**
      * Title string used by the back button on iOS.
      * Defaults to the previous scene's title.
@@ -133,7 +134,7 @@ export type NativeStackNavigationOptions = {
      *
      * @platform ios, web
      */
-    headerBackTitle?: string;
+    headerBackTitle?: string | undefined;
     /**
      * Style object for header back title. Supported properties:
      * - fontFamily
@@ -144,11 +145,17 @@ export type NativeStackNavigationOptions = {
      * @platform ios, web
      */
     headerBackTitleStyle?: StyleProp<{
-        fontFamily?: string;
-        fontSize?: number;
-    }>;
+        fontFamily?: string | undefined;
+        fontSize?: number | undefined;
+    }> | undefined;
     /**
-     * Icon to display in the header as the icon in the back button.
+     * Icon to display in the header in the back button.
+     *
+     * Supported types:
+     * - image: custom image source
+     * - sfSymbol: SF Symbol icon (iOS only - when using custom header)
+     * - materialSymbol: material symbol icon (Android only)
+     *
      * Defaults to back icon image for the platform
      * - A chevron on iOS
      * - An arrow on Android
@@ -161,10 +168,7 @@ export type NativeStackNavigationOptions = {
      * }
      * ```
      */
-    headerBackIcon?: {
-        type: 'image';
-        source: ImageSourcePropType;
-    };
+    headerBackIcon?: Icon | undefined;
     /**
      * Style of the header when a large title is shown.
      * The large title is shown if `headerLargeTitleEnabled` is `true` and
@@ -178,8 +182,8 @@ export type NativeStackNavigationOptions = {
      * @platform ios
      */
     headerLargeStyle?: StyleProp<{
-        backgroundColor?: ColorValue;
-    }>;
+        backgroundColor?: ColorValue | undefined;
+    }> | undefined;
     /**
      * Whether to enable header with large title which collapses to regular header on scroll.
      *
@@ -191,7 +195,7 @@ export type NativeStackNavigationOptions = {
      *
      * @platform ios
      */
-    headerLargeTitleEnabled?: boolean;
+    headerLargeTitleEnabled?: boolean | undefined;
     /**
      * Whether drop shadow of header is visible when a large title is shown.
      *
@@ -199,7 +203,7 @@ export type NativeStackNavigationOptions = {
      *
      * @platform ios
      */
-    headerLargeTitleShadowVisible?: boolean;
+    headerLargeTitleShadowVisible?: boolean | undefined;
     /**
      * Style object for large title in header. Supported properties:
      * - fontFamily
@@ -212,33 +216,33 @@ export type NativeStackNavigationOptions = {
      * @platform ios
      */
     headerLargeTitleStyle?: StyleProp<{
-        fontFamily?: string;
-        fontSize?: number;
-        fontWeight?: string;
-        color?: ColorValue;
-    }>;
+        fontFamily?: string | undefined;
+        fontSize?: number | undefined;
+        fontWeight?: string | undefined;
+        color?: ColorValue | undefined;
+    }> | undefined;
     /**
      * Whether to show the header. The header is shown by default.
      * Setting this to `false` hides the header.
      */
-    headerShown?: boolean;
+    headerShown?: boolean | undefined;
     /**
      * Style object for header. Supported properties:
      * - backgroundColor
      */
     headerStyle?: StyleProp<{
-        backgroundColor?: ColorValue;
-    }>;
+        backgroundColor?: ColorValue | undefined;
+    }> | undefined;
     /**
      * Whether to hide the elevation shadow (Android) or the bottom border (iOS) on the header.
      */
-    headerShadowVisible?: boolean;
+    headerShadowVisible?: boolean | undefined;
     /**
      * Boolean indicating whether the navigation bar is translucent.
      * Setting this to `true` makes the header absolutely positioned,
      * and changes the background color to `transparent` unless specified in `headerStyle`.
      */
-    headerTransparent?: boolean;
+    headerTransparent?: boolean | undefined;
     /**
      * Blur effect for the translucent header.
      * The `headerTransparent` option needs to be set to `true` for this to work.
@@ -249,23 +253,23 @@ export type NativeStackNavigationOptions = {
      *
      * @platform ios
      */
-    headerBlurEffect?: ScreenStackHeaderConfigProps['blurEffect'];
+    headerBlurEffect?: ScreenStackHeaderConfigProps['blurEffect'] | undefined;
     /**
      * Tint color for the header. Changes the color of back button and title.
      */
-    headerTintColor?: ColorValue;
+    headerTintColor?: ColorValue | undefined;
     /**
      * Function which returns a React Element to render as the background of the header.
      * This is useful for using backgrounds such as an image, a gradient, blur effect etc.
      * You can use this with `headerTransparent` to render content underneath a translucent header.
      */
-    headerBackground?: () => React.ReactNode;
+    headerBackground?: (() => React.ReactNode) | undefined;
     /**
      * Function which returns a React Element to display on the left side of the header.
      * This replaces the back button. See `headerBackVisible` to show the back button along side left element.
      * Will be overriden by `headerLeftItems` on iOS.
      */
-    headerLeft?: (props: NativeStackHeaderBackProps) => React.ReactNode;
+    headerLeft?: ((props: NativeStackHeaderBackProps) => React.ReactNode) | undefined;
     /**
      * Whether the liquid glass background is visible for the item.
      *
@@ -274,12 +278,12 @@ export type NativeStackNavigationOptions = {
      *
      * Defaults to `true`.
      */
-    headerLeftBackgroundVisible?: boolean;
+    headerLeftBackgroundVisible?: boolean | undefined;
     /**
      * Function which returns a React Element to display on the right side of the header.
      * Will be overriden by `headerRightItems` on iOS.
      */
-    headerRight?: (props: NativeStackHeaderItemProps) => React.ReactNode;
+    headerRight?: ((props: NativeStackHeaderItemProps) => React.ReactNode) | undefined;
     /**
      * Whether the liquid glass background is visible for the item.
      *
@@ -288,7 +292,7 @@ export type NativeStackNavigationOptions = {
      *
      * Defaults to `true`.
      */
-    headerRightBackgroundVisible?: boolean;
+    headerRightBackgroundVisible?: boolean | undefined;
     /**
      * Function which returns an array of items to display as on the left side of the header.
      * Overrides `headerLeft`.
@@ -297,7 +301,7 @@ export type NativeStackNavigationOptions = {
      *
      * @platform ios
      */
-    unstable_headerLeftItems?: (props: NativeStackHeaderItemProps) => NativeStackHeaderItem[];
+    unstable_headerLeftItems?: ((props: NativeStackHeaderItemProps) => NativeStackHeaderItem[]) | undefined;
     /**
      * Function which returns an array of items to display as on the right side of the header.
      * Overrides `headerRight`.
@@ -306,7 +310,7 @@ export type NativeStackNavigationOptions = {
      *
      * @platform ios
      */
-    unstable_headerRightItems?: (props: NativeStackHeaderItemProps) => NativeStackHeaderItem[];
+    unstable_headerRightItems?: ((props: NativeStackHeaderItemProps) => NativeStackHeaderItem[]) | undefined;
     /**
      * String or a function that returns a React Element to be used by the header.
      * Defaults to screen `title` or route name.
@@ -324,15 +328,15 @@ export type NativeStackNavigationOptions = {
         /**
          * Tint color for the header.
          */
-        tintColor?: ColorValue;
-    }) => React.ReactNode);
+        tintColor?: ColorValue | undefined;
+    }) => React.ReactNode) | undefined;
     /**
      * How to align the the header title.
      * Defaults to `left` on platforms other than iOS.
      *
      * Not supported on iOS. It's always `center` on iOS and cannot be changed.
      */
-    headerTitleAlign?: 'left' | 'center';
+    headerTitleAlign?: 'left' | 'center' | undefined;
     /**
      * Style object for header title. Supported properties:
      * - fontFamily
@@ -341,16 +345,16 @@ export type NativeStackNavigationOptions = {
      * - color
      */
     headerTitleStyle?: StyleProp<Pick<TextStyle, 'fontFamily' | 'fontSize' | 'fontWeight'> & {
-        color?: ColorValue;
-    }>;
+        color?: ColorValue | undefined;
+    }> | undefined;
     /**
      * Options to render a native search bar.
      * You also need to specify `contentInsetAdjustmentBehavior="automatic"` in your `ScrollView`, `FlatList` etc.
      * If you don't have a `ScrollView`, specify `headerTransparent: false`.
      */
-    headerSearchBarOptions?: Omit<SearchBarProps, 'onChangeText'> & {
-        onChange?: SearchBarProps['onChangeText'];
-    };
+    headerSearchBarOptions?: (Omit<SearchBarProps, 'onChangeText'> & {
+        onChange?: SearchBarProps['onChangeText'] | undefined;
+    }) | undefined;
     /**
      * Boolean indicating whether to show the menu on longPress of iOS >= 14 back button. Defaults to `true`.
      * Requires `react-native-screens` version >=3.3.0.
@@ -359,7 +363,7 @@ export type NativeStackNavigationOptions = {
      *
      * @platform ios
      */
-    headerBackButtonMenuEnabled?: boolean;
+    headerBackButtonMenuEnabled?: boolean | undefined;
     /**
      * How the back button displays icon and title.
      *
@@ -381,25 +385,25 @@ export type NativeStackNavigationOptions = {
      *
      * @platform ios, web
      */
-    headerBackButtonDisplayMode?: ScreenStackHeaderConfigProps['backButtonDisplayMode'];
+    headerBackButtonDisplayMode?: ScreenStackHeaderConfigProps['backButtonDisplayMode'] | undefined;
     /**
      * Whether the home indicator should prefer to stay hidden on this screen. Defaults to `false`.
      *
      * @platform ios
      */
-    autoHideHomeIndicator?: boolean;
+    autoHideHomeIndicator?: boolean | undefined;
     /**
      * Whether the keyboard should hide when swiping to the previous screen. Defaults to `false`.
      *
      * @platform ios
      */
-    keyboardHandlingEnabled?: boolean;
+    keyboardHandlingEnabled?: boolean | undefined;
     /**
      * Sets the visibility of the navigation bar. Defaults to `false`.
      *
      * @platform android
      */
-    navigationBarHidden?: boolean;
+    navigationBarHidden?: boolean | undefined;
     /**
      * Sets the status bar animation (similar to the `StatusBar` component).
      * On Android, setting either `fade` or `slide` will set the transition of status bar color. On iOS, this option applies to appereance animation of the status bar.
@@ -411,7 +415,7 @@ export type NativeStackNavigationOptions = {
      *
      * @platform android, ios
      */
-    statusBarAnimation?: ScreenProps['statusBarAnimation'];
+    statusBarAnimation?: ScreenProps['statusBarAnimation'] | undefined;
     /**
      * Whether the status bar should be hidden on this screen.
      * Requires setting `View controller-based status bar appearance -> YES` in your Info.plist file.
@@ -420,7 +424,7 @@ export type NativeStackNavigationOptions = {
      *
      * @platform android, ios
      */
-    statusBarHidden?: boolean;
+    statusBarHidden?: boolean | undefined;
     /**
      * Sets the status bar color (similar to the `StatusBar` component).
      * Requires setting `View controller-based status bar appearance -> YES` (or removing the config) in your `Info.plist` file.
@@ -432,7 +436,7 @@ export type NativeStackNavigationOptions = {
      *
      * @platform android, ios
      */
-    statusBarStyle?: ScreenProps['statusBarStyle'];
+    statusBarStyle?: ScreenProps['statusBarStyle'] | undefined;
     /**
      * Sets the direction in which you should swipe to dismiss the screen.
      * When using `vertical` option, options `fullScreenGestureEnabled: true`, `animationMatchesGesture: true` and `animation: 'slide_from_bottom'` are set by default.
@@ -443,11 +447,11 @@ export type NativeStackNavigationOptions = {
      *
      * @platform ios
      */
-    gestureDirection?: ScreenProps['swipeDirection'];
+    gestureDirection?: ScreenProps['swipeDirection'] | undefined;
     /**
      * Style object for the scene content.
      */
-    contentStyle?: StyleProp<ViewStyle>;
+    contentStyle?: StyleProp<ViewStyle> | undefined;
     /**
      * Whether the gesture to dismiss should use animation provided to `animation` prop. Defaults to `false`.
      *
@@ -455,7 +459,7 @@ export type NativeStackNavigationOptions = {
      *
      * @platform ios
      */
-    animationMatchesGesture?: boolean;
+    animationMatchesGesture?: boolean | undefined;
     /**
      * Whether the gesture to dismiss should work on the whole screen. The behavior depends on iOS version.
      *
@@ -470,7 +474,7 @@ export type NativeStackNavigationOptions = {
      *
      * @platform ios
      */
-    fullScreenGestureEnabled?: boolean;
+    fullScreenGestureEnabled?: boolean | undefined;
     /**
      * iOS 18 and below. Controls whether the full screen dismiss gesture has shadow under view during transition.
      * The gesture uses custom transition and thus doesn't have a shadow by default. When enabled, a custom shadow view
@@ -482,7 +486,7 @@ export type NativeStackNavigationOptions = {
      *
      * @platform ios
      */
-    fullScreenGestureShadowEnabled?: boolean;
+    fullScreenGestureShadowEnabled?: boolean | undefined;
     /**
      * Whether you can use gestures to dismiss this screen. Defaults to `true`.
      *
@@ -490,13 +494,13 @@ export type NativeStackNavigationOptions = {
      *
      * @platform ios
      */
-    gestureEnabled?: boolean;
+    gestureEnabled?: boolean | undefined;
     /**
      * Use it to restrict the distance from the edges of screen in which the gesture should be recognized. To be used alongside `fullScreenGestureEnabled`.
      *
      * @platform ios
      */
-    gestureResponseDistance?: ScreenProps['gestureResponseDistance'];
+    gestureResponseDistance?: ScreenProps['gestureResponseDistance'] | undefined;
     /**
      * The type of animation to use when this screen replaces another screen. Defaults to `pop`.
      *
@@ -506,7 +510,7 @@ export type NativeStackNavigationOptions = {
      *
      * Only supported on iOS and Android.
      */
-    animationTypeForReplace?: ScreenProps['replaceAnimation'];
+    animationTypeForReplace?: ScreenProps['replaceAnimation'] | undefined;
     /**
      * How the screen should animate when pushed or popped.
      *
@@ -525,7 +529,7 @@ export type NativeStackNavigationOptions = {
      *
      * Only supported on iOS and Android.
      */
-    animation?: ScreenProps['stackAnimation'];
+    animation?: ScreenProps['stackAnimation'] | undefined;
     /**
      * Duration (in milliseconds) for the following transition animations on iOS:
      * - `slide_from_bottom`
@@ -541,7 +545,7 @@ export type NativeStackNavigationOptions = {
      *
      * @platform ios
      */
-    animationDuration?: number;
+    animationDuration?: number | undefined;
     /**
      * How should the screen be presented.
      *
@@ -557,7 +561,7 @@ export type NativeStackNavigationOptions = {
      *
      * Only supported on iOS and Android.
      */
-    presentation?: Exclude<ScreenProps['stackPresentation'], 'push'> | 'card';
+    presentation?: Exclude<ScreenProps['stackPresentation'], 'push'> | 'card' | undefined;
     /**
      * Describes heights where a sheet can rest.
      * Works only when `presentation` is set to `formSheet`.
@@ -576,7 +580,7 @@ export type NativeStackNavigationOptions = {
      *
      * Defaults to `[1.0]`.
      */
-    sheetAllowedDetents?: number[] | 'fitToContents';
+    sheetAllowedDetents?: number[] | 'fitToContents' | undefined;
     /**
      * Integer value describing elevation of the sheet, impacting shadow on the top edge of the sheet.
      *
@@ -586,7 +590,7 @@ export type NativeStackNavigationOptions = {
      *
      * @platform Android
      */
-    sheetElevation?: number;
+    sheetElevation?: number | undefined;
     /**
      * Whether the sheet should expand to larger detent when scrolling.
      * Works only when `presentation` is set to `formSheet`.
@@ -594,7 +598,7 @@ export type NativeStackNavigationOptions = {
      *
      * @platform ios
      */
-    sheetExpandsWhenScrolledToEdge?: boolean;
+    sheetExpandsWhenScrolledToEdge?: boolean | undefined;
     /**
      * The corner radius that the sheet will try to render with.
      * Works only when `presentation` is set to `formSheet`.
@@ -603,7 +607,7 @@ export type NativeStackNavigationOptions = {
      *
      * If left unset system default is used.
      */
-    sheetCornerRadius?: number;
+    sheetCornerRadius?: number | undefined;
     /**
      * Index of the detent the sheet should expand to after being opened.
      * Works only when `stackPresentation` is set to `formSheet`.
@@ -615,7 +619,7 @@ export type NativeStackNavigationOptions = {
      *
      * Defaults to `0` - which represents first detent in the detents array.
      */
-    sheetInitialDetentIndex?: number | 'last';
+    sheetInitialDetentIndex?: number | 'last' | undefined;
     /**
      * Boolean indicating whether the sheet shows a grabber at the top.
      * Works only when `presentation` is set to `formSheet`.
@@ -623,7 +627,7 @@ export type NativeStackNavigationOptions = {
      *
      * @platform ios
      */
-    sheetGrabberVisible?: boolean;
+    sheetGrabberVisible?: boolean | undefined;
     /**
      * The largest sheet detent for which a view underneath won't be dimmed.
      * Works only when `presentation` is set to `formSheet`.
@@ -643,7 +647,7 @@ export type NativeStackNavigationOptions = {
      *
      * Defaults to `none`, indicating that the dimming view should be always present.
      */
-    sheetLargestUndimmedDetentIndex?: number | 'none' | 'last';
+    sheetLargestUndimmedDetentIndex?: number | 'none' | 'last' | undefined;
     /**
      * Whether the sheet content should be rendered behind the Status Bar or display cutouts.
      *
@@ -659,7 +663,7 @@ export type NativeStackNavigationOptions = {
      *
      * @platform android
      */
-    sheetShouldOverflowTopInset?: boolean;
+    sheetShouldOverflowTopInset?: boolean | undefined;
     /**
      * Whether the default native animation should be used when the sheet's with
      * `fitToContents` content size changes.
@@ -676,7 +680,7 @@ export type NativeStackNavigationOptions = {
      *
      * @platform android
      */
-    sheetResizeAnimationEnabled?: boolean;
+    sheetResizeAnimationEnabled?: boolean | undefined;
     /**
      * The display orientation to use for the screen.
      *
@@ -692,15 +696,7 @@ export type NativeStackNavigationOptions = {
      *
      * Only supported on iOS and Android.
      */
-    orientation?: ScreenProps['screenOrientation'];
-    /**
-     * Whether inactive screens should be suspended from re-rendering. Defaults to `false`.
-     * Defaults to `true` when `enableFreeze()` is run at the top of the application.
-     * Requires `react-native-screens` version >=3.16.0.
-     *
-     * Only supported on iOS and Android.
-     */
-    freezeOnBlur?: boolean;
+    orientation?: ScreenProps['screenOrientation'] | undefined;
     /**
      * Configures the scroll edge effect for the _content ScrollView_ (the ScrollView that is present in first descendants chain of the Screen).
      * Depending on values set, it will blur the scrolling content below certain UI elements (header items, search bar)
@@ -725,11 +721,11 @@ export type NativeStackNavigationOptions = {
      * @supported iOS 26 or higher
      */
     scrollEdgeEffects?: {
-        bottom?: ScrollEdgeEffect;
-        left?: ScrollEdgeEffect;
-        right?: ScrollEdgeEffect;
-        top?: ScrollEdgeEffect;
-    };
+        bottom?: ScrollEdgeEffect | undefined;
+        left?: ScrollEdgeEffect | undefined;
+        right?: ScrollEdgeEffect | undefined;
+        top?: ScrollEdgeEffect | undefined;
+    } | undefined;
     /**
      * Footer component that can be used alongside formSheet stack presentation style.
      *
@@ -742,24 +738,25 @@ export type NativeStackNavigationOptions = {
      *
      * @platform android
      */
-    unstable_sheetFooter?: () => React.ReactNode;
-};
-type PlatformIconShared = {
-    type: 'image';
-    source: ImageSourcePropType;
+    unstable_sheetFooter?: (() => React.ReactNode) | undefined;
     /**
-     * Whether to apply tint color to the icon.
-     * Defaults to `true`.
+     * What should happen when screens become inactive.
+     * - `pause`: Effects are cleaned up.
+     * - `unmount`: Screen is unmounted
+     * - `none`: Screen renders normally
      *
-     * @platform ios
+     * Defaults to `pause`.
+     *
+     * Preloaded screens won't be paused until after navigated to.
+     * This makes sure that effects are run to initialize the screen.
+     *
+     * Screens with nested navigators and last 2 screens won't be unmounted.
      */
-    tinted?: boolean;
+    inactiveBehavior?: 'pause' | 'unmount' | 'none' | undefined;
 };
-type PlatformIconIOSSfSymbol = {
-    type: 'sfSymbol';
-    name: SFSymbol;
-};
-type PlatformIconIOS = PlatformIconIOSSfSymbol | PlatformIconShared;
+type IconIOS = Extract<Icon, {
+    type: 'image' | 'sfSymbol';
+}>;
 type SharedHeaderItem = {
     /**
      * Label of the item.
@@ -769,59 +766,59 @@ type SharedHeaderItem = {
      * Style for the item label.
      */
     labelStyle?: {
-        fontFamily?: string;
-        fontSize?: number;
-        fontWeight?: string;
-        color?: ColorValue;
-    };
+        fontFamily?: string | undefined;
+        fontSize?: number | undefined;
+        fontWeight?: string | undefined;
+        color?: ColorValue | undefined;
+    } | undefined;
     /**
      * Icon for the item
      */
-    icon?: PlatformIconIOS;
+    icon?: IconIOS | undefined;
     /**
      * The variant of the item.
      * "prominent" only available from iOS 26.0 and later.
      *
      * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitem/style-swift.property
      */
-    variant?: 'plain' | 'done' | 'prominent';
+    variant?: 'plain' | 'done' | 'prominent' | undefined;
     /**
      * The tint color to apply to the item.
      *
      * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitem/tintcolor
      */
-    tintColor?: ColorValue;
+    tintColor?: ColorValue | undefined;
     /**
      * Whether the item is in a disabled state.
      */
-    disabled?: boolean;
+    disabled?: boolean | undefined;
     /**
      * The width of the item.
      *
      * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitem/width
      */
-    width?: number;
+    width?: number | undefined;
     /**
      * Whether the background this item may share with other items in the bar should be hidden.
      * Only available from iOS 26.0 and later.
      *
      * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitem/hidessharedbackground
      */
-    hidesSharedBackground?: boolean;
+    hidesSharedBackground?: boolean | undefined;
     /**
      * Whether this item can share a background with other items.
      * Only available from iOS 26.0 and later.
      *
      * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitem/sharesbackground
      */
-    sharesBackground?: boolean;
+    sharesBackground?: boolean | undefined;
     /**
      * An identifier used to match items across transitions.
      * Only available from iOS 26.0 and later.
      *
      * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitem/identifier
      */
-    identifier?: string;
+    identifier?: string | undefined;
     /**
      * A badge to display on a item.
      * Only available from iOS 26.0 and later.
@@ -837,21 +834,21 @@ type SharedHeaderItem = {
          * Style of the badge.
          */
         style?: {
-            color?: ColorValue;
-            backgroundColor?: ColorValue;
-            fontFamily?: string;
-            fontSize?: number;
-            fontWeight?: string;
-        };
-    };
+            color?: ColorValue | undefined;
+            backgroundColor?: ColorValue | undefined;
+            fontFamily?: string | undefined;
+            fontSize?: number | undefined;
+            fontWeight?: string | undefined;
+        } | undefined;
+    } | undefined;
     /**
      * Accessibility label for the item.
      */
-    accessibilityLabel?: string;
+    accessibilityLabel?: string | undefined;
     /**
      * Accessibility hint for the item.
      */
-    accessibilityHint?: string;
+    accessibilityHint?: string | undefined;
 };
 /**
  * A button item in the header.
@@ -870,7 +867,7 @@ export type NativeStackHeaderItemButton = SharedHeaderItem & {
      *
      * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitem/isselected
      */
-    selected?: boolean;
+    selected?: boolean | undefined;
 };
 /**
  * An action item in a menu.
@@ -884,11 +881,11 @@ export type NativeStackHeaderItemMenuAction = {
     /**
      * The secondary text displayed alongside the label of the menu item.
      */
-    description?: string;
+    description?: string | undefined;
     /**
      * Icon for the menu item.
      */
-    icon?: PlatformIconIOSSfSymbol;
+    icon?: IconIOS | undefined;
     /**
      * Function to call when the menu item is pressed.
      */
@@ -898,31 +895,31 @@ export type NativeStackHeaderItemMenuAction = {
      *
      * Read more: https://developer.apple.com/documentation/uikit/uimenuelement/state
      */
-    state?: 'on' | 'off' | 'mixed';
+    state?: 'on' | 'off' | 'mixed' | undefined;
     /**
      * Whether to apply disabled style to the item.
      *
      * Read more: https://developer.apple.com/documentation/uikit/uimenuelement/attributes/disabled
      */
-    disabled?: boolean;
+    disabled?: boolean | undefined;
     /**
      * Whether to apply destructive style to the item.
      *
      * Read more: https://developer.apple.com/documentation/uikit/uimenuelement/attributes/destructive
      */
-    destructive?: boolean;
+    destructive?: boolean | undefined;
     /**
      * Whether to apply hidden style to the item.
      *
      * Read more: https://developer.apple.com/documentation/uikit/uimenuelement/attributes/hidden
      */
-    hidden?: boolean;
+    hidden?: boolean | undefined;
     /**
-     * Whether to keep the menu presented after firing the element’s action.
+     * Whether to keep the menu presented after firing the element's action.
      *
      * Read more: https://developer.apple.com/documentation/uikit/uimenuelement/attributes/keepsmenupresented
      */
-    keepsMenuPresented?: boolean;
+    keepsMenuPresented?: boolean | undefined;
     /**
      * An elaborated title that explains the purpose of the action.
      *
@@ -931,7 +928,7 @@ export type NativeStackHeaderItemMenuAction = {
      *
      * Read more: https://developer.apple.com/documentation/uikit/uiaction/discoverabilitytitle
      */
-    discoverabilityLabel?: string;
+    discoverabilityLabel?: string | undefined;
 };
 /**
  * A submenu item that contains other menu items.
@@ -945,7 +942,7 @@ export type NativeStackHeaderItemMenuSubmenu = {
     /**
      * Icon for the submenu item.
      */
-    icon?: PlatformIconIOSSfSymbol;
+    icon?: IconIOS | undefined;
     /**
      * Whether the menu is displayed inline with the parent menu.
      * By default, submenus are displayed after expanding the parent menu item.
@@ -955,7 +952,7 @@ export type NativeStackHeaderItemMenuSubmenu = {
      *
      * Read more: https://developer.apple.com/documentation/uikit/uimenu/options-swift.struct/displayinline
      */
-    inline?: boolean;
+    inline?: boolean | undefined;
     /**
      * How the submenu items are displayed.
      * - `default`: menu items are displayed normally.
@@ -965,13 +962,13 @@ export type NativeStackHeaderItemMenuSubmenu = {
      *
      * Read more: https://developer.apple.com/documentation/uikit/uimenu/options-swift.struct/displayaspalette
      */
-    layout?: 'default' | 'palette';
+    layout?: 'default' | 'palette' | undefined;
     /**
      * Whether to apply destructive style to the menu item.
      *
      * Read more: https://developer.apple.com/documentation/uikit/uimenuelement/attributes/destructive
      */
-    destructive?: boolean;
+    destructive?: boolean | undefined;
     /**
      * Whether multiple items in the submenu can be selected, i.e. in "on" state.
      *
@@ -979,7 +976,7 @@ export type NativeStackHeaderItemMenuSubmenu = {
      *
      * Read more: https://developer.apple.com/documentation/uikit/uimenu/options-swift.struct/singleselection
      */
-    multiselectable?: boolean;
+    multiselectable?: boolean | undefined;
     /**
      * Array of menu items (actions or submenus).
      */
@@ -996,7 +993,7 @@ export type NativeStackHeaderItemMenu = SharedHeaderItem & {
      *
      * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitem/changesselectionasprimaryaction
      */
-    changesSelectionAsPrimaryAction?: boolean;
+    changesSelectionAsPrimaryAction?: boolean | undefined;
     /**
      * Menu for the item.
      */
@@ -1004,7 +1001,7 @@ export type NativeStackHeaderItemMenu = SharedHeaderItem & {
         /**
          * Optional title to show on top of the menu.
          */
-        title?: string;
+        title?: string | undefined;
         /**
          * Whether multiple items in the submenu can be selected, i.e. in "on" state.
          *
@@ -1012,7 +1009,7 @@ export type NativeStackHeaderItemMenu = SharedHeaderItem & {
          *
          * Read more: https://developer.apple.com/documentation/uikit/uimenu/options-swift.struct/singleselection
          */
-        multiselectable?: boolean;
+        multiselectable?: boolean | undefined;
         /**
          * How the submenu items are displayed.
          * - `default`: menu items are displayed normally.
@@ -1022,7 +1019,7 @@ export type NativeStackHeaderItemMenu = SharedHeaderItem & {
          *
          * Read more: https://developer.apple.com/documentation/uikit/uimenu/options-swift.struct/displayaspalette
          */
-        layout?: 'default' | 'palette';
+        layout?: 'default' | 'palette' | undefined;
         /**
          * Array of menu items (actions or submenus).
          */
@@ -1054,7 +1051,7 @@ export type NativeStackHeaderItemCustom = {
      *
      * Read more: https://developer.apple.com/documentation/uikit/uibarbuttonitem/hidessharedbackground
      */
-    hidesSharedBackground?: boolean;
+    hidesSharedBackground?: boolean | undefined;
 };
 /**
  * An item that can be displayed in the header.