feat: implement freezeOnBlur

Author: okwasniewski

apps/example/src/App.tsx

@@ -29,6 +29,7 @@ import NativeBottomTabsSVGs from './Examples/NativeBottomTabsSVGs';
 import NativeBottomTabsRemoteIcons from './Examples/NativeBottomTabsRemoteIcons';
 import NativeBottomTabsUnmounting from './Examples/NativeBottomTabsUnmounting';
 import NativeBottomTabsCustomTabBar from './Examples/NativeBottomTabsCustomTabBar';
+import NativeBottomTabsFreezeOnBlur from './Examples/NativeBottomTabsFreezeOnBlur';
 
 const FourTabsIgnoreSafeArea = () => {
   return <FourTabs ignoresTopSafeArea />;
@@ -130,6 +131,10 @@ const examples = [
     component: HiddenTab,
     name: 'Four Tabs - With Hidden Tab',
   },
+  {
+    component: NativeBottomTabsFreezeOnBlur,
+    name: 'Native Bottom Tabs with freezeOnBlur',
+  },
   {
     component: NativeBottomTabsSVGs,
     name: 'Native Bottom Tabs with SVG Icons',

apps/example/src/Examples/NativeBottomTabs.tsx

@@ -20,6 +20,9 @@ function NativeBottomTabs() {
       tabBarStyle={{
         backgroundColor: '#1E2D2F',
       }}
+      screenOptions={{
+        freezeOnBlur: true,
+      }}
       rippleColor="#F7DBA7"
       tabLabelStyle={{
         fontFamily: 'Avenir',
@@ -42,7 +45,7 @@ function NativeBottomTabs() {
             console.log(
               `${Platform.OS}: Long press detected on tab with key ${data.target} at the screen level.`
             );
-            setLabel('New Article')
+            setLabel('New Article');
           },
         }}
         options={{

apps/example/src/Examples/NativeBottomTabsFreezeOnBlur.tsx

@@ -0,0 +1,115 @@
+import * as React from 'react';
+import { Platform, StyleSheet, Text, View } from 'react-native';
+import { createNativeBottomTabNavigator } from '@bottom-tabs/react-navigation';
+
+const store = new Set<Dispatch>();
+
+type Dispatch = (value: number) => void;
+
+function useValue() {
+  const [value, setValue] = React.useState<number>(0);
+
+  React.useEffect(() => {
+    const dispatch = (value: number) => {
+      setValue(value);
+    };
+    store.add(dispatch);
+    return () => {
+      store.delete(dispatch);
+    };
+  }, [setValue]);
+
+  return value;
+}
+
+function HomeScreen() {
+  return (
+    <View style={styles.screenContainer}>
+      <Text>Home!</Text>
+    </View>
+  );
+}
+
+function DetailsScreen(props: any) {
+  const value = useValue();
+  const screenName = props?.route?.params?.screenName;
+  // only 1 'render' should appear at the time
+  console.log(`${Platform.OS} Details Screen render ${value} ${screenName}`);
+  return (
+    <View style={styles.screenContainer}>
+      <Text>Details!</Text>
+      <Text style={{ alignSelf: 'center' }}>
+        Details Screen {value} {screenName ? screenName : ''}{' '}
+      </Text>
+    </View>
+  );
+}
+const Tab = createNativeBottomTabNavigator();
+
+export default function NativeBottomTabsFreezeOnBlur() {
+  React.useEffect(() => {
+    let timer = 0;
+    const interval = setInterval(() => {
+      timer = timer + 1;
+      store.forEach((dispatch) => dispatch(timer));
+    }, 3000);
+    return () => clearInterval(interval);
+  }, []);
+
+  return (
+    <Tab.Navigator
+      screenOptions={{
+        freezeOnBlur: true,
+      }}
+    >
+      <Tab.Screen
+        name="Article"
+        component={HomeScreen}
+        initialParams={{
+          screenName: 'Article',
+        }}
+        options={{
+          tabBarIcon: () => require('../../assets/icons/article_dark.png'),
+        }}
+      />
+      <Tab.Screen
+        name="Albums"
+        component={DetailsScreen}
+        initialParams={{
+          screenName: 'Albums',
+        }}
+        options={{
+          tabBarIcon: () => require('../../assets/icons/grid_dark.png'),
+        }}
+      />
+      <Tab.Screen
+        name="Contact"
+        component={DetailsScreen}
+        initialParams={{
+          screenName: 'Contact',
+        }}
+        options={{
+          tabBarIcon: () => require('../../assets/icons/person_dark.png'),
+        }}
+      />
+      <Tab.Screen
+        name="Chat"
+        component={DetailsScreen}
+        initialParams={{
+          screenName: 'Chat',
+        }}
+        options={{
+          tabBarIcon: () => require('../../assets/icons/chat_dark.png'),
+        }}
+      />
+    </Tab.Navigator>
+  );
+}
+
+const styles = StyleSheet.create({
+  screenContainer: {
+    flex: 1,
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+});

packages/react-native-bottom-tabs/package.json

@@ -113,6 +113,7 @@
     "version": "0.41.2"
   },
   "dependencies": {
+    "react-freeze": "^1.0.0",
     "sf-symbols-typescript": "^2.0.0",
     "use-latest-callback": "^0.2.1"
   },

packages/react-native-bottom-tabs/src/DelayedFreeze.tsx

@@ -0,0 +1,31 @@
+import React from 'react';
+import { Freeze } from 'react-freeze';
+
+interface FreezeWrapperProps {
+  freeze: boolean;
+  children: React.ReactNode;
+}
+
+// Delay before applying freeze effect
+const ANIMATION_DELAY = 100;
+
+// This component delays the freeze effect by animation delay.
+// So that the screen is not frozen immediately causing background flash.
+function DelayedFreeze({ freeze, children }: FreezeWrapperProps) {
+  // flag used for determining whether freeze should be enabled
+  const [freezeState, setFreezeState] = React.useState(false);
+
+  React.useEffect(() => {
+    const id = setTimeout(() => {
+      setFreezeState(freeze);
+    }, ANIMATION_DELAY);
+
+    return () => {
+      clearTimeout(id);
+    };
+  }, [freeze]);
+
+  return <Freeze freeze={freeze ? freezeState : false}>{children}</Freeze>;
+}
+
+export default DelayedFreeze;

packages/react-native-bottom-tabs/src/Screen.tsx

@@ -0,0 +1,25 @@
+import { View } from 'react-native';
+import type { ViewProps } from 'react-native';
+import DelayedFreeze from './DelayedFreeze';
+
+interface ScreenProps extends ViewProps {
+  children: React.ReactNode;
+  freeze: boolean;
+  focused?: boolean;
+}
+
+function Screen({ children, freeze, focused, ...props }: ScreenProps) {
+  return (
+    <View
+      collapsable={false}
+      pointerEvents={focused ? 'auto' : 'none'}
+      accessibilityElementsHidden={!focused}
+      importantForAccessibility={focused ? 'auto' : 'no-hide-descendants'}
+      {...props}
+    >
+      <DelayedFreeze freeze={freeze}>{children}</DelayedFreeze>
+    </View>
+  );
+}
+
+export default Screen;

packages/react-native-bottom-tabs/src/TabView.tsx

@@ -1,5 +1,6 @@
 import React from 'react';
 import type { TabViewItems } from './TabViewNativeComponent';
+import Screen from './Screen';
 import {
   type ColorValue,
   Image,
@@ -116,8 +117,16 @@ interface Props<Route extends BaseRoute> {
    */
   getTestID?: (props: { route: Route }) => string | undefined;
 
+  /**
+   * Custom tab bar to render. Set to `null` to hide the tab bar completely.
+   */
   tabBar?: () => React.ReactNode;
 
+  /**
+   * Get freezeOnBlur for the current screen. Uses false by default.
+   */
+  getFreezeOnBlur?: (props: { route: Route }) => boolean | undefined;
+
   tabBarStyle?: {
     /**
      * Background color of the tab bar.
@@ -177,6 +186,7 @@ const TabView = <Route extends BaseRoute>({
   hapticFeedbackEnabled = false,
   // Android's native behavior is to show labels when there are less than 4 tabs. We leave it as undefined to use the platform default behavior.
   labeled = Platform.OS !== 'android' ? true : undefined,
+  getFreezeOnBlur = ({ route }: { route: Route }) => route.freezeOnBlur,
   tabBar: renderCustomTabBar,
   tabBarStyle,
   tabLabelStyle,
@@ -317,23 +327,20 @@ const TabView = <Route extends BaseRoute>({
           }
 
           const focused = route.key === focusedKey;
+          const freeze = !focused ? getFreezeOnBlur({ route }) : false;
 
           return (
-            <View
+            <Screen
               key={route.key}
-              collapsable={false}
-              pointerEvents={focused ? 'auto' : 'none'}
-              accessibilityElementsHidden={!focused}
-              importantForAccessibility={
-                focused ? 'auto' : 'no-hide-descendants'
-              }
-              style={[{ position: 'absolute' }, measuredDimensions]}
+              freeze={!!freeze}
+              focused={focused}
+              style={[styles.screen, measuredDimensions]}
             >
               {renderScene({
                 route,
                 jumpTo,
               })}
-            </View>
+            </Screen>
           );
         })}
       </NativeTabView>
@@ -348,6 +355,9 @@ const styles = StyleSheet.create({
     height: '100%',
     flex: 1,
   },
+  screen: {
+    position: 'absolute',
+  },
 });
 
 export default TabView;

packages/react-native-bottom-tabs/src/types.ts

@@ -15,6 +15,7 @@ export type BaseRoute = {
   activeTintColor?: string;
   hidden?: boolean;
   testID?: string;
+  freezeOnBlur?: boolean;
 };
 
 export type NavigationState<Route extends BaseRoute> = {

packages/react-navigation/src/types.ts

@@ -91,6 +91,13 @@ export type NativeBottomTabNavigationOptions = {
    * TestID for the tab.
    */
   tabBarButtonTestID?: string;
+
+  /**
+   * Whether inactive screens should be suspended from re-rendering. Defaults to `false`.
+   *
+   * Only supported on iOS and Android.
+   */
+  freezeOnBlur?: boolean;
 };
 
 export type NativeBottomTabDescriptor = Descriptor<
@@ -127,6 +134,7 @@ export type NativeBottomTabNavigationConfig = Partial<
     | 'getActiveTintColor'
     | 'getTestID'
     | 'tabBar'
+    | 'getFreezeOnBlur'
   >
 > & {
   tabBar?: (props: BottomTabBarProps) => React.ReactNode;

packages/react-navigation/src/views/NativeBottomTabView.tsx

@@ -63,6 +63,9 @@ export default function NativeBottomTabView({
         return null;
       }}
       getLazy={({ route }) => descriptors[route.key]?.options.lazy ?? true}
+      getFreezeOnBlur={({ route }) =>
+        descriptors[route.key]?.options.freezeOnBlur
+      }
       onTabLongPress={(index) => {
         const route = state.routes[index];
         if (!route) {