@react-navigation/material-top-tabs 8.0.0-alpha.4 → 8.0.0-alpha.42

package/src/types.tsx

@@ -1,3 +1,4 @@
+import type { Icon } from '@react-navigation/elements';
 import type {
   DefaultNavigatorOptions,
   Descriptor,
@@ -78,7 +79,7 @@ export type MaterialTopTabNavigationOptions = {
   /**
    * Title text for the screen.
    */
-  title?: string;
+  title?: string | undefined;
 
   /**
    * Title string of a tab displayed in the tab bar
@@ -92,145 +93,163 @@ export type MaterialTopTabNavigationOptions = {
         focused: boolean;
         color: ColorValue;
         children: string;
-      }) => React.ReactNode);
+      }) => React.ReactNode)
+    | undefined;
 
   /**
    * Accessibility label for the tab button. This is read by the screen reader when the user taps the tab.
    * It's recommended to set this if you don't have a label for the tab.
    */
-  tabBarAccessibilityLabel?: string;
+  tabBarAccessibilityLabel?: string | undefined;
 
   /**
    * Whether label font should scale to respect Text Size accessibility settings.
    */
-  tabBarAllowFontScaling?: boolean;
+  tabBarAllowFontScaling?: boolean | undefined;
 
   /**
    * Whether the tab label should be visible. Defaults to `true`.
    */
-  tabBarShowLabel?: boolean;
+  tabBarShowLabel?: boolean | undefined;
 
   /**
-   * A function that given { focused: boolean, color: ColorValue } returns a React.Node to display in the tab bar.
+   * Icon to display for the tab.
    */
-  tabBarIcon?: (props: {
-    focused: boolean;
-    color: ColorValue;
-  }) => React.ReactElement;
+  tabBarIcon?:
+    | Icon
+    | ((props: {
+        focused: boolean;
+        color: ColorValue;
+        size: number;
+      }) => Icon | React.ReactNode);
 
   /**
    * Whether the tab icon should be visible. Defaults to `false`.
    */
-  tabBarShowIcon?: boolean;
+  tabBarShowIcon?: boolean | undefined;
 
   /**
    * Function that returns a React element to use as a badge for the tab.
    */
-  tabBarBadge?: () => React.ReactElement;
+  tabBarBadge?: (() => React.ReactElement) | undefined;
 
   /**
    * Function that returns a React element as the tab bar indicator.
    */
-  tabBarIndicator?: (
-    props: Omit<
-      Parameters<
-        NonNullable<React.ComponentProps<typeof TabBar>['renderIndicator']>
-      >[0],
-      'navigationState'
-    > & { state: TabNavigationState<ParamListBase> }
-  ) => React.ReactNode;
+  tabBarIndicator?:
+    | ((
+        props: Omit<
+          Parameters<
+            NonNullable<React.ComponentProps<typeof TabBar>['renderIndicator']>
+          >[0],
+          'navigationState'
+        > & { state: TabNavigationState<ParamListBase> }
+      ) => React.ReactNode)
+    | undefined;
+
+  /**
+   * Variant of the tab bar.
+   *
+   * The following variants are available:
+   *
+   * - `primary`: the indicator matches the label & icon width and is centered under the tab.
+   * - `secondary`: the indicator spans the full tab width.
+   *
+   * Defaults to `primary`.
+   */
+  tabBarVariant?: 'primary' | 'secondary' | undefined;
 
   /**
    * Style object for the tab bar indicator.
    */
-  tabBarIndicatorStyle?: StyleProp<ViewStyle>;
+  tabBarIndicatorStyle?: StyleProp<ViewStyle> | undefined;
 
   /**
    * Style object for the view containing the tab bar indicator.
    */
-  tabBarIndicatorContainerStyle?: StyleProp<ViewStyle>;
+  tabBarIndicatorContainerStyle?: StyleProp<ViewStyle> | undefined;
 
   /**
    * ID to locate this tab button in tests.
    */
-  tabBarButtonTestID?: string;
+  tabBarButtonTestID?: string | undefined;
 
   /**
    * Color for the icon and label in the active tab.
    */
-  tabBarActiveTintColor?: ColorValue;
+  tabBarActiveTintColor?: ColorValue | undefined;
 
   /**
    * Color for the icon and label in the inactive tabs.
    */
-  tabBarInactiveTintColor?: ColorValue;
+  tabBarInactiveTintColor?: ColorValue | undefined;
 
   /**
    * Color for material ripple (Android >= 5.0 only).
    */
-  tabBarPressColor?: ColorValue;
+  tabBarPressColor?: ColorValue | undefined;
 
   /**
    * Opacity for pressed tab (iOS and Android < 5.0 only).
    */
-  tabBarPressOpacity?: number;
+  tabBarPressOpacity?: number | undefined;
 
   /**
    * Boolean indicating whether the tab bar bounces when overscrolling.
    */
-  tabBarBounces?: boolean;
+  tabBarBounces?: boolean | undefined;
 
   /**
    * Boolean indicating whether to make the tab bar scrollable.
    *
    * If you set this to `true`, you should also specify a width in `tabBarItemStyle` to improve the performance of initial render.
    */
-  tabBarScrollEnabled?: boolean;
+  tabBarScrollEnabled?: boolean | undefined;
 
   /**
    * Style object for the tab label.
    */
-  tabBarLabelStyle?: StyleProp<TextStyle>;
+  tabBarLabelStyle?: StyleProp<TextStyle> | undefined;
 
   /**
    * Style object for the individual tab items.
    */
-  tabBarItemStyle?: StyleProp<ViewStyle>;
+  tabBarItemStyle?: StyleProp<ViewStyle> | undefined;
 
   /**
    * Style object for the view containing the tab items.
    */
-  tabBarContentContainerStyle?: StyleProp<ViewStyle>;
+  tabBarContentContainerStyle?: StyleProp<ViewStyle> | undefined;
 
   /**
    * Style object for the the tab bar.
    */
-  tabBarStyle?: StyleProp<ViewStyle>;
+  tabBarStyle?: StyleProp<ViewStyle> | undefined;
 
   /**
    * Gap between tabs
    */
-  tabBarGap?: number;
+  tabBarGap?: number | undefined;
 
   /**
    * Allows to customize the android ripple effect (Android >= 5.0 only).
    *
-   * Default: `{ borderless: true }`
+   * Default: `{ borderless: false, foreground: true }`
    */
-  tabBarAndroidRipple?: PressableAndroidRippleConfig;
+  tabBarAndroidRipple?: PressableAndroidRippleConfig | undefined;
 
   /**
    * Whether to enable swipe gestures when this screen is focused.
    * Swipe gestures are enabled by default. Passing `false` will disable swipe gestures,
    * but the user can still switch tabs by pressing the tab bar.
    */
-  swipeEnabled?: boolean;
+  swipeEnabled?: boolean | undefined;
 
   /**
    * Whether to enable animations when switching between tabs by pressing on the tab bar or programmatically.
    * Switching tab via swipe gesture will still result in an animation.
    */
-  animationEnabled?: boolean;
+  animationEnabled?: boolean | undefined;
 
   /**
    * Whether this screen should be lazily rendered. When this is set to `true`,
@@ -243,13 +262,13 @@ export type MaterialTopTabNavigationOptions = {
    * when they come into the viewport. You can use the `lazyPlaceholder` prop to customize
    * what the user sees during this short period.
    */
-  lazy?: boolean;
+  lazy?: boolean | undefined;
 
   /**
    * When `lazy` is enabled, you can specify how many adjacent screens should be preloaded in advance with this prop.
    * This value defaults to `0` which means lazy pages are loaded as they come into the viewport.
    */
-  lazyPreloadDistance?: number;
+  lazyPreloadDistance?: number | undefined;
 
   /**
    * Function that returns a React element to render if this screen hasn't been rendered yet.
@@ -259,12 +278,25 @@ export type MaterialTopTabNavigationOptions = {
    *
    * By default, this renders `null`.
    */
-  lazyPlaceholder?: () => React.ReactNode;
+  lazyPlaceholder?: (() => React.ReactNode) | undefined;
 
   /**
    * Style object for the component wrapping the screen content.
    */
-  sceneStyle?: StyleProp<ViewStyle>;
+  sceneStyle?: StyleProp<ViewStyle> | undefined;
+
+  /**
+   * What should happen when screens become inactive.
+   * - `pause`: Effects are cleaned up.
+   * - `none`: Screen renders normally
+   *
+   * Defaults to `pause`.
+   *
+   * If you set `lazy: false` or preload a screen,
+   * It won't be paused until after the first time it becomes focused.
+   * This makes sure that effects are run to initialize the screen.
+   */
+  inactiveBehavior?: ('pause' | 'none') | undefined;
 };
 
 export type MaterialTopTabDescriptor = Descriptor<
@@ -297,11 +329,11 @@ export type MaterialTopTabNavigationConfig = Omit<
   /**
    * Function that returns a React element to display as the tab bar.
    */
-  tabBar?: (props: MaterialTopTabBarProps) => React.ReactNode;
+  tabBar?: ((props: MaterialTopTabBarProps) => React.ReactNode) | undefined;
   /**
    * Function that returns a React element to override the underlying adapter.
    */
-  adapter?: TabViewProps<Route<string>>['renderAdapter'];
+  adapter?: TabViewProps<Route<string>>['renderAdapter'] | undefined;
 };
 
 export type MaterialTopTabBarProps = Pick<

package/src/utils/useTabAnimation.tsx

@@ -3,7 +3,7 @@ import * as React from 'react';
 import { TabAnimationContext } from './TabAnimationContext';
 
 export function useTabAnimation() {
-  const animation = React.useContext(TabAnimationContext);
+  const animation = React.use(TabAnimationContext);
 
   if (animation === undefined) {
     throw new Error(

package/src/views/MaterialTopTabBar.tsx

@@ -1,19 +1,9 @@
-import { Text } from '@react-navigation/elements';
+import { PlatformIcon, Text } from '@react-navigation/elements';
 import { Color } from '@react-navigation/elements/internal';
-import {
-  type ParamListBase,
-  type TabNavigationState,
-  useLinkBuilder,
-  useLocale,
-  useTheme,
-} from '@react-navigation/native';
+import { useLinkBuilder, useLocale, useTheme } from '@react-navigation/native';
+import * as React from 'react';
 import { type ColorValue, StyleSheet } from 'react-native';
-import {
-  type Route,
-  TabBar,
-  TabBarIndicator,
-  type TabDescriptor,
-} from 'react-native-tab-view';
+import { type Route, TabBar, type TabDescriptor } from 'react-native-tab-view';
 
 import type { MaterialTopTabBarProps } from '../types';
 
@@ -53,18 +43,34 @@ export function MaterialTopTabBar({
   const { direction } = useLocale();
   const { buildHref } = useLinkBuilder();
 
-  const focusedOptions = descriptors[state.routes[state.index].key].options;
+  const focusedRoute = state.routes[state.index];
+
+  if (focusedRoute == null) {
+    throw new Error(`Couldn't find a route at index ${state.index}.`);
+  }
+
+  const focusedOptions = descriptors[focusedRoute.key]?.options ?? {};
+  const tabBarVariant = focusedOptions.tabBarVariant ?? 'primary';
 
   const activeColor: ColorValue =
-    focusedOptions.tabBarActiveTintColor ?? colors.text;
+    focusedOptions.tabBarActiveTintColor ??
+    (tabBarVariant === 'primary' ? colors.primary : colors.text);
+
   const inactiveColor: ColorValue =
     focusedOptions.tabBarInactiveTintColor ??
-    Color(activeColor)?.alpha(0.5).string() ??
-    (dark ? 'rgba(255, 255, 255, 0.5)' : 'rgba(0, 0, 0, 0.5)');
+    Color(colors.text)?.alpha(0.68).string() ??
+    (dark ? 'rgba(255, 255, 255, 0.68)' : 'rgba(0, 0, 0, 0.68)');
+
+  const pressColor: ColorValue =
+    focusedOptions.tabBarPressColor ??
+    Color(tabBarVariant === 'primary' ? colors.primary : colors.text)
+      ?.alpha(0.12)
+      .string() ??
+    (dark ? 'rgba(255, 255, 255, 0.12)' : 'rgba(0, 0, 0, 0.12)');
 
   const tabBarOptions = Object.fromEntries(
     state.routes.map((route) => {
-      const { options } = descriptors[route.key];
+      const options = descriptors[route.key]?.options ?? {};
 
       const {
         title,
@@ -79,6 +85,41 @@ export function MaterialTopTabBar({
         tabBarLabelStyle,
       } = options;
 
+      let icon;
+
+      if (tabBarShowIcon === false) {
+        icon = undefined;
+      } else if (tabBarIcon) {
+        icon = ({
+          focused,
+          color,
+          size,
+        }: {
+          focused: boolean;
+          color: ColorValue;
+          size: number;
+        }) => {
+          const iconValue =
+            typeof tabBarIcon === 'function'
+              ? tabBarIcon({ focused, color, size })
+              : tabBarIcon;
+
+          if (React.isValidElement(iconValue)) {
+            return iconValue;
+          }
+
+          if (
+            typeof iconValue === 'object' &&
+            iconValue != null &&
+            'type' in iconValue
+          ) {
+            return <PlatformIcon icon={iconValue} size={size} color={color} />;
+          }
+
+          return null;
+        };
+      }
+
       return [
         route.key,
         {
@@ -86,14 +127,14 @@ export function MaterialTopTabBar({
           testID: tabBarButtonTestID,
           accessibilityLabel: tabBarAccessibilityLabel,
           badge: tabBarBadge,
-          icon: tabBarShowIcon === false ? undefined : tabBarIcon,
+          icon,
           label:
             tabBarShowLabel === false
               ? undefined
               : typeof tabBarLabel === 'function'
                 ? ({ labelText, color }: MaterialLabelProps) =>
                     tabBarLabel({
-                      focused: state.routes[state.index].key === route.key,
+                      focused: focusedRoute.key === route.key,
                       color,
                       children: labelText ?? route.name,
                     })
@@ -113,6 +154,8 @@ export function MaterialTopTabBar({
     })
   );
 
+  const tabBarIndicator = focusedOptions.tabBarIndicator;
+
   return (
     <TabBar
       {...rest}
@@ -123,7 +166,7 @@ export function MaterialTopTabBar({
       bounces={focusedOptions.tabBarBounces}
       activeColor={activeColor}
       inactiveColor={inactiveColor}
-      pressColor={focusedOptions.tabBarPressColor}
+      pressColor={pressColor}
       pressOpacity={focusedOptions.tabBarPressOpacity}
       tabStyle={focusedOptions.tabBarItemStyle}
       indicatorStyle={[
@@ -131,10 +174,14 @@ export function MaterialTopTabBar({
         focusedOptions.tabBarIndicatorStyle,
       ]}
       gap={focusedOptions.tabBarGap}
+      variant={tabBarVariant}
       android_ripple={focusedOptions.tabBarAndroidRipple}
       indicatorContainerStyle={focusedOptions.tabBarIndicatorContainerStyle}
       contentContainerStyle={focusedOptions.tabBarContentContainerStyle}
-      style={[{ backgroundColor: colors.card }, focusedOptions.tabBarStyle]}
+      style={[
+        { backgroundColor: colors.card, borderBottomColor: colors.border },
+        focusedOptions.tabBarStyle,
+      ]}
       onTabPress={({ route, preventDefault }) => {
         const event = navigation.emit({
           type: 'tabPress',
@@ -152,16 +199,12 @@ export function MaterialTopTabBar({
           target: route.key,
         })
       }
-      renderIndicator={({ navigationState: state, ...rest }) => {
-        return focusedOptions.tabBarIndicator ? (
-          focusedOptions.tabBarIndicator({
-            state: state as TabNavigationState<ParamListBase>,
-            ...rest,
-          })
-        ) : (
-          <TabBarIndicator navigationState={state} {...rest} />
-        );
-      }}
+      renderIndicator={
+        tabBarIndicator
+          ? ({ navigationState: _, ...rest }) =>
+              tabBarIndicator({ ...rest, state })
+          : undefined
+      }
     />
   );
 }
@@ -170,7 +213,6 @@ const styles = StyleSheet.create({
   label: {
     textAlign: 'center',
     fontSize: 14,
-    margin: 4,
     backgroundColor: 'transparent',
   },
 });

package/src/views/MaterialTopTabView.tsx

@@ -1,3 +1,4 @@
+import { ActivityView } from '@react-navigation/elements/internal';
 import {
   CommonActions,
   type ParamListBase,
@@ -6,6 +7,8 @@ import {
   useLocale,
   useTheme,
 } from '@react-navigation/native';
+import { useMemo, useState } from 'react';
+import { type Animated, StyleSheet } from 'react-native';
 import { TabView } from 'react-native-tab-view';
 
 import type {
@@ -13,6 +16,7 @@ import type {
   MaterialTopTabDescriptorMap,
   MaterialTopTabNavigationConfig,
   MaterialTopTabNavigationHelpers,
+  MaterialTopTabNavigationOptions,
 } from '../types';
 import { TabAnimationContext } from '../utils/TabAnimationContext';
 import { MaterialTopTabBar } from './MaterialTopTabBar';
@@ -54,7 +58,21 @@ export function MaterialTopTabView({
     });
   };
 
-  const focusedOptions = descriptors[state.routes[state.index].key].options;
+  const focusedRoute = state.routes[state.index];
+
+  if (focusedRoute == null) {
+    throw new Error(`Couldn't find a route at index ${state.index}.`);
+  }
+
+  const focusedDescriptor = descriptors[focusedRoute.key];
+
+  if (focusedDescriptor == null) {
+    throw new Error(
+      `Couldn't find a descriptor for route '${focusedRoute.key}'.`
+    );
+  }
+
+  const focusedOptions = focusedDescriptor.options;
 
   return (
     <TabView
@@ -62,23 +80,42 @@ export function MaterialTopTabView({
       onIndexChange={(index) => {
         const route = state.routes[index];
 
+        if (route == null) {
+          throw new Error(`Couldn't find a route at index ${index}.`);
+        }
+
         navigation.dispatch({
-          ...CommonActions.navigate(route),
+          ...CommonActions.navigate(route.name, route.params),
           target: state.key,
         });
       }}
-      renderScene={({ route, position }) => (
-        <TabAnimationContext.Provider value={{ position }}>
-          {descriptors[route.key].render()}
-        </TabAnimationContext.Provider>
-      )}
+      renderScene={({ route, position }) => {
+        const descriptor = descriptors[route.key];
+
+        if (descriptor == null) {
+          throw new Error(
+            `Couldn't find a descriptor for route '${route.key}'.`
+          );
+        }
+
+        return (
+          <SceneContent
+            focused={route.key === focusedRoute.key}
+            preloaded={state.preloadedRouteKeys.includes(route.key)}
+            position={position}
+            options={descriptor.options}
+          >
+            {descriptor.render()}
+          </SceneContent>
+        );
+      }}
       navigationState={state}
       renderTabBar={renderTabBar}
       renderLazyPlaceholder={({ route }) =>
-        descriptors[route.key].options.lazyPlaceholder?.() ?? null
+        descriptors[route.key]?.options.lazyPlaceholder?.() ?? null
       }
       lazy={({ route }) =>
-        descriptors[route.key].options.lazy === true &&
+        descriptors[route.key]?.options.lazy === true &&
         !state.preloadedRouteKeys.includes(route.key)
       }
       lazyPreloadDistance={focusedOptions.lazyPreloadDistance}
@@ -105,3 +142,57 @@ export function MaterialTopTabView({
     />
   );
 }
+
+function SceneContent({
+  focused,
+  preloaded,
+  position,
+  options,
+  children,
+}: {
+  focused: boolean;
+  preloaded: boolean;
+  position: Animated.AnimatedInterpolation<number>;
+  options: MaterialTopTabNavigationOptions;
+  children: React.ReactNode;
+}) {
+  const { inactiveBehavior = 'pause', lazy } = options;
+
+  const [loaded, setLoaded] = useState(focused);
+
+  if (focused && !loaded) {
+    setLoaded(true);
+  }
+
+  const animationContext = useMemo(() => ({ position }), [position]);
+
+  // For preloaded screens and if lazy is false,
+  // Keep them active so that the effects can run
+  const isActive =
+    inactiveBehavior === 'none' ||
+    focused ||
+    preloaded ||
+    (lazy === false && !loaded);
+
+  return (
+    <TabAnimationContext.Provider value={animationContext}>
+      <ActivityView
+        mode={isActive ? 'normal' : 'paused'}
+        visible={
+          // Tabs can be swiped quickly
+          // So we keep all tabs visible to avoid flash of blank screen
+          true
+        }
+        style={styles.scene}
+      >
+        {children}
+      </ActivityView>
+    </TabAnimationContext.Provider>
+  );
+}
+
+const styles = StyleSheet.create({
+  scene: {
+    flex: 1,
+  },
+});