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,
+          },
+          renderBackground: 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

@@ -154,6 +154,10 @@ A callback that gets called when the current screen will disappear. This is call
 
 Boolean indicating whether to prevent current screen from being dismissed. Defaults to `false`.
 
+### `renderBackground`
+
+Callback returning the custom React element to be rendered as the background of the screen.
+
 ### `replaceAnimation`
 
 Allows for the customization of the type of animation to use when this screen replaces another screen at the top of the stack. The following values are currently supported:

src/components/ScreenStackItem.tsx

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

src/types.tsx

@@ -336,6 +336,14 @@ export interface ScreenProps extends ViewProps {
    */
   preventNativeDismiss?: boolean;
   ref?: React.Ref<View>;
+  /**
+   * Callback returning the 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.
+   */
+  renderBackground?: () => React.ReactNode;
   /**
    * How should the screen replacing another screen animate. Defaults to `pop`.
    * The following values are currently supported: