feat(Stack): Add background component

apps/src/tests/Test3348.tsx

@@ -0,0 +1,59 @@
+import * as React from 'react';
+import { Text, View, StyleSheet, Image } from 'react-native';
+import { NavigationContainer } from '@react-navigation/native';
+import { createNativeStackNavigator } from '@react-navigation/native-stack';
+import Colors from '../shared/styling/Colors';
+
+const Stack = createNativeStackNavigator();
+
+const CustomBackgroundComponent = () => (
+  <Image
+    source={{
+      uri: 'https://fastly.picsum.photos/id/309/400/800.jpg?hmac=Pjy1rvSFQNX9tqavzeWNpy3dfWBGjLkY0doRN50JXBA',
+    }}
+    style={{
+      height: '100%',
+      aspectRatio: 1
+    }}
+  />
+);
+
+function HomeScreen() {
+  return (
+    <View style={styles.screenContent}>
+      <Text style={styles.text}>Home Screen</Text>
+    </View>
+  );
+}
+
+const App = () => {
+  return (
+    <NavigationContainer>
+      <Stack.Navigator
+        screenOptions={{
+          contentStyle: {
+            padding: 35,
+          },
+          backgroundComponent: CustomBackgroundComponent,
+        }}>
+        <Stack.Screen name="Home" component={HomeScreen} />
+      </Stack.Navigator>
+    </NavigationContainer>
+  );
+};
+
+const styles = StyleSheet.create({
+  screenContent: {
+    flex: 1,
+    backgroundColor: Colors.Navy,
+    justifyContent: 'center',
+    alignItems: 'center',
+    borderRadius: 10,
+  },
+  text: {
+    fontSize: 24,
+    color: Colors.White,
+  },
+});
+
+export default App;

apps/src/tests/index.ts

@@ -155,6 +155,7 @@ export { default as Test3239 } from './Test3239';
 export { default as Test3265 } from './Test3265';
 export { default as Test3271 } from './Test3271';
 export { default as Test3282 } from './Test3282';
+// export { default as Test3348 } from './Test3348'; // Waiting for react-navigation changes to propagate
 export { default as TestScreenAnimation } from './TestScreenAnimation';
 export { default as TestScreenAnimationV5 } from './TestScreenAnimationV5';
 export { default as TestHeader } from './TestHeader';

guides/GUIDE_FOR_LIBRARY_AUTHORS.md

@@ -42,6 +42,10 @@ The `ScreenStackItem` component is a convenience wrapper around `Screen` that's
 
 Below is the list of additional properties that can be used for `ScreenStackItem` component:
 
+### `backgroundComponent`
+
+Custom React element to be rendered as the background of the screen.
+
 ### `customAnimationOnSwipe` (iOS only)
 
 Boolean indicating that swipe dismissal should trigger animation provided by `stackAnimation`. Defaults to `false`.

src/components/ScreenStackItem.tsx

@@ -36,6 +36,7 @@ function ScreenStackItem(
     children,
     headerConfig,
     activityState,
+    backgroundComponent,
     shouldFreeze,
     stackPresentation,
     sheetAllowedDetents,
@@ -100,6 +101,11 @@ function ScreenStackItem(
         contentStyle={contentStyle}
         style={debugContainerStyle}
         stackPresentation={stackPresentation ?? 'push'}>
+        {backgroundComponent && (
+          <View style={StyleSheet.absoluteFill} pointerEvents="none">
+            {backgroundComponent()}
+          </View>
+        )}
         {shouldUseSafeAreaView ? (
           <SafeAreaView edges={getSafeAreaEdges(headerConfig)}>
             {children}

src/types.tsx

@@ -147,6 +147,14 @@ export interface ScreenProps extends ViewProps {
    */
   shouldFreeze?: boolean;
   children?: React.ReactNode;
+  /**
+   * Optional custom React element to be rendered as the background of the screen.
+   *
+   * This component will be rendered behind all foreground screen content.
+   * You can provide any valid React element, such as an ImageBackground,
+   * gradient, or a styled View.
+   */
+  backgroundComponent?: () => React.ReactNode;
   /**
    * Boolean indicating that swipe dismissal should trigger animation provided by `stackAnimation`. Defaults to `false`.
    *