feat(navigation-bar): modernize to Material Design 3

docs/6.x/docs/guides/_meta.json

@@ -7,7 +7,7 @@
   "recommended-libraries",
   "contributing",
   "theming-with-react-navigation",
-  "bottom-navigation",
+  "navigation-bar",
   "react-navigation",
   "rtl",
   "ripple-effect",

docs/6.x/docs/guides/migration.md

@@ -74,8 +74,7 @@ Hardcoded default test IDs have been removed for the components listed below:
 
 - `Appbar.Content`: `appbar-content`
 - `Appbar.Header`: `appbar-header`
-- `BottomNavigation`: `bottom-navigation`
-- `BottomNavigation.Bar`: `bottom-navigation-bar`
+- `NavigationBar`: `bottom-navigation` and `bottom-navigation-bar` (v5 `BottomNavigation` and `BottomNavigation.Bar`)
 - `Button`: `button`
 - `Card`: `card`
 - `Chip`: `chip`
@@ -99,7 +98,6 @@ If you were relying on internal test IDs, update your tests not to rely on inter
 
 Some components now accept explicit `testID` props for their interactable elements:
 
-- `BottomNavigation`: `barTestID` for the internal `BottomNavigation.Bar`, replacing the previous `${testID}-bar` derivation.
 - `Chip`: `closeIconTestID` for the close icon button.
 - `Dialog` and `Modal`: `overlayTestID` for the overlay displayed behind the content.
 - `Menu`: `overlayTestID` for the overlay displayed behind the menu.
@@ -114,6 +112,75 @@ The `style` props for `Appbar` and `Appbar.Header` no longer accept `Animated.Va
 
 The `style.elevation` property is no longer supported. Use the `elevated` prop to control Appbar elevation.
 
+### BottomNavigation
+
+`BottomNavigation` has been removed. Paper no longer ships a component that owns your tab scenes; the Material 3 navigation bar is now `NavigationBar`, a standalone bar you render next to your own navigator (React Navigation, or your own state).
+
+| v5                                                                    | v6                                                                       |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `BottomNavigation`, `BottomNavigation.Bar`                            | `NavigationBar`                                                          |
+| `BottomNavigationProps`, `BottomNavigationRoute`                      | `NavigationBarProps`, `NavigationBarRoute`                               |
+| `BottomNavigation.SceneMap`, `renderScene`, `onIndexChange`           | render the active scene yourself, alongside the bar                      |
+| `getLazy`, `route.lazy`                                               | removed (the bar no longer owns the scenes)                              |
+| `sceneAnimationEnabled`, `sceneAnimationType`, `sceneAnimationEasing` | removed with the scene container                                         |
+| `shifting`                                                            | removed (including the active-icon shift and inactive-label transitions) |
+| `barStyle`                                                            | `style`                                                                  |
+| `animationEasing`                                                     | removed (the indicator uses M3 motion from the theme)                |
+| `barStyle` with `Animated.Value`                                      | `style` with static styles only                                          |
+| n/a                                                                   | new `variant` (`'stacked' \| 'horizontal'`) for the item layout          |
+
+```diff
+- <BottomNavigation
+-   navigationState={{ index, routes }}
+-   onIndexChange={setIndex}
+-   renderScene={BottomNavigation.SceneMap({ home: HomeScreen, settings: SettingsScreen })}
+-   barStyle={{ backgroundColor: theme.colors.surfaceContainer }}
+- />
++ <>
++   {renderScene({ route: routes[index] })}
++   <NavigationBar
++     navigationState={{ index, routes }}
++     onTabPress={({ route }) => setIndex(routes.findIndex((r) => r.key === route.key))}
++     style={{ backgroundColor: theme.colors.surfaceContainer }}
++   />
++ </>
+```
+
+`onTabPress` & `onTabLongPress` callbacks receive only pressed `route`. The v5 event object also carried `preventDefault()` & `defaultPrevented`, so code that reads them now throws `preventDefault is not a function`. The bar never navigates on its own, so navigator's own `tabPress` event decides whether press is handled:
+
+```diff
+  tabBar={({ navigation, state, descriptors, insets }) => (
+    <NavigationBar
+      navigationState={state}
+      safeAreaInsets={insets}
+-     onTabPress={({ route, preventDefault }) => {
++     onTabPress={({ route }) => {
+        const event = navigation.emit({
+          type: 'tabPress',
+          target: route.key,
+          canPreventDefault: true,
+        });
+
+-       if (event.defaultPrevented) {
+-         preventDefault();
+-       } else {
++       if (!event.defaultPrevented) {
+          navigation.dispatch({
+            ...CommonActions.navigate(route.name, route.params),
+            target: state.key,
+          });
+        }
+      }}
+    />
+  )}
+```
+
+The `animationEasing` prop is gone along with animation it configured. Active indicator now follows the motion from theme (`theme.motion`) and honors reduce motion preference.
+
+Unlike v5 `barStyle`, the `style` prop no longer accepts `Animated.Value` or `Animated.AnimatedInterpolation`. Pass static styles.
+
+`NavigationBar` also does not set a default `testID`. If your tests looked up `bottom-navigation-bar` (or its `-container` / `-content` / `-content-wrapper` children), pass a `testID` explicitly.
+
 ### Surface
 
 - The `elevation` prop no longer accepts a React Native `Animated.Value`. Any `elevation` changes are animated automatically.

docs/6.x/docs/guides/bottom-navigation.md → docs/6.x/docs/guides/navigation-bar.md

@@ -1,27 +1,25 @@
 ---
-title: Using BottomNavigation with React Navigation
+title: Using NavigationBar with React Navigation
 ---
 
 Build a Material Design bottom tab bar by combining two pieces:
 
 - `@react-navigation/bottom-tabs` handles routing, state, and screen options.
-- `BottomNavigation.Bar` renders the Material 3 tab bar (ripple, badges, shifting/labeled modes).
-
-<img src="/react-native-paper/screenshots/material-bottom-tabs.gif" style={{ width: '420px', maxWidth: '100%', margin: '16px 0' }} />
+- `NavigationBar` renders the Material 3 navigation bar (state layers, badges, and stacked or horizontal item layouts).
 
 :::info
 Install [`@react-navigation/native`](https://reactnavigation.org/docs/getting-started) and [`@react-navigation/bottom-tabs`](https://reactnavigation.org/docs/bottom-tab-navigator) first.
 :::
 
 ## Quick example
 
-Pass a `BottomNavigation.Bar` to the navigator's `tabBar` prop. The bar reads navigation state and dispatches `tabPress` events back:
+Pass a `NavigationBar` to the navigator's `tabBar` prop. The bar reads navigation state and dispatches `tabPress` events back:
 
 ```jsx
 import MaterialCommunityIcons from '@react-native-vector-icons/material-design-icons';
 import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
 import { CommonActions } from '@react-navigation/native';
-import { BottomNavigation } from 'react-native-paper';
+import { NavigationBar } from 'react-native-paper';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 
 const Tab = createBottomTabNavigator();
@@ -31,20 +29,17 @@ function MyTabs() {
 
   return (
     <Tab.Navigator
-      screenOptions={{ animation: 'shift' }}
       tabBar={({ navigation, state, descriptors }) => (
-        <BottomNavigation.Bar
+        <NavigationBar
           navigationState={state}
           safeAreaInsets={insets}
-          onTabPress={({ route, preventDefault }) => {
+          onTabPress={({ route }) => {
             const event = navigation.emit({
               type: 'tabPress',
               target: route.key,
               canPreventDefault: true,
             });
-            if (event.defaultPrevented) {
-              preventDefault();
-            } else {
+            if (!event.defaultPrevented) {
               navigation.dispatch({
                 ...CommonActions.navigate(route.name, route.params),
                 target: state.key,

docs/6.x/docs/guides/theming.mdx

@@ -502,7 +502,7 @@ Now you can use your `FancyButton` component everywhere instead of using `Button
 ## Dark Theme
 
 Since 3.0 we adapt dark theme to follow [Material design guidelines](https://material.io/design/color/dark-theme.html). <br/>
-In contrast to light theme, dark theme by default uses `surface` colour instead of `primary` on large components like `Appbar` or `BottomNavigation`.<br/>
+In contrast to light theme, dark theme by default uses `surface` colour instead of `primary` on large components like `Appbar` or `NavigationBar`.<br/>
 The dark theme adds a white overlay with opacity depending on elevation of surfaces. It uses it for the better accentuation of surface elevation. Using only shadow is highly imperceptible on dark surfaces.
 
 If you don't use a custom theme, Paper will automatically change between the default theme and the default dark theme, depending on device settings.

docs/component-docs.config.ts

@@ -46,10 +46,6 @@ const pages = {
   },
   Badge: 'Badge',
   Banner: 'Banner',
-  BottomNavigation: {
-    BottomNavigation: 'BottomNavigation/BottomNavigation',
-    BottomNavigationBar: 'BottomNavigation/BottomNavigationBar',
-  },
   Button: {
     Button: 'Button/Button',
   },
@@ -115,6 +111,9 @@ const pages = {
     MenuItem: 'Menu/MenuItem',
   },
   Modal: 'Modal',
+  NavigationBar: {
+    NavigationBar: 'NavigationBar/NavigationBar',
+  },
   Portal: {
     Portal: {
       source: 'Portal/Portal',

docs/src/data/extendedExamples.ts

@@ -1,10 +1,7 @@
-import {
-  dynamicCode,
-  staticCode,
-} from './extendedExamples/BottomNavigationBar.ts';
+import { dynamicCode, staticCode } from './extendedExamples/NavigationBar.ts';
 
 export const extendedExamples = {
-  'BottomNavigation.Bar': {
+  NavigationBar: {
     'with React Navigation': {
       static: staticCode,
       dynamic: dynamicCode,

docs/src/data/extendedExamples/BottomNavigationBar.ts → docs/src/data/extendedExamples/NavigationBar.ts

@@ -1,6 +1,6 @@
 export const staticCode = `import { Text, View } from 'react-native';
 import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
-import { Provider, BottomNavigation } from 'react-native-paper';
+import { Provider, NavigationBar } from 'react-native-paper';
 import MaterialCommunityIcons from '@react-native-vector-icons/material-design-icons';
 import {
   CommonActions,
@@ -24,23 +24,18 @@ function SettingsScreen() {
 }
 
 const MyTabs = createBottomTabNavigator({
-  screenOptions: {
-    animation: 'shift',
-  },
   tabBar: ({ navigation, state, descriptors, insets }) => (
-    <BottomNavigation.Bar
+    <NavigationBar
       navigationState={state}
       safeAreaInsets={insets}
-      onTabPress={({ route, preventDefault }) => {
+      onTabPress={({ route }) => {
         const event = navigation.emit({
           type: 'tabPress',
           target: route.key,
           canPreventDefault: true,
         });
 
-        if (event.defaultPrevented) {
-          preventDefault();
-        } else {
+        if (!event.defaultPrevented) {
           navigation.dispatch({
             ...CommonActions.navigate(route.name, route.params),
             target: state.key,
@@ -102,7 +97,7 @@ export default function App() {
 export const dynamicCode = `import { Text, View } from 'react-native';
 import { NavigationContainer, CommonActions } from '@react-navigation/native';
 import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
-import { Provider, BottomNavigation } from 'react-native-paper';
+import { Provider, NavigationBar } from 'react-native-paper';
 import MaterialCommunityIcons from '@react-native-vector-icons/material-design-icons';
 
 function HomeScreen() {
@@ -128,23 +123,18 @@ export default function App() {
     <Provider>
       <NavigationContainer>
         <Tab.Navigator
-          screenOptions={{
-            animation: 'shift',
-          }}
           tabBar={({ navigation, state, descriptors, insets }) => (
-            <BottomNavigation.Bar
+            <NavigationBar
               navigationState={state}
               safeAreaInsets={insets}
-              onTabPress={({ route, preventDefault }) => {
+              onTabPress={({ route }) => {
                 const event = navigation.emit({
                   type: 'tabPress',
                   target: route.key,
                   canPreventDefault: true,
                 });
 
-                if (event.defaultPrevented) {
-                  preventDefault();
-                } else {
+                if (!event.defaultPrevented) {
                   navigation.dispatch({
                     ...CommonActions.navigate(route.name, route.params),
                     target: state.key,

docs/src/data/screenshots.ts

@@ -19,8 +19,6 @@ export const screenshots = {
     dot: 'screenshots/badge-3.png',
   },
   Banner: 'screenshots/banner.gif',
-  BottomNavigation: 'screenshots/bottom-navigation.gif',
-  'BottomNavigation.Bar': 'screenshots/bottom-navigation-tabs.jpg',
   Button: {
     text: 'screenshots/button-1.png',
     outlined: 'screenshots/button-2.png',
@@ -105,6 +103,7 @@ export const screenshots = {
   },
   'Menu.Item': 'screenshots/menu-item.png',
   Modal: 'screenshots/modal.gif',
+  NavigationBar: 'screenshots/navigation-bar.png',
   ProgressBar: 'screenshots/progress-bar.png',
   RadioButton: {
     'Android (enabled)': 'screenshots/radio-enabled.android.png',

example/src/ExampleList.tsx

@@ -10,7 +10,6 @@ import AvatarExample from './Examples/AvatarExample';
 import BadgeExample from './Examples/BadgeExample';
 import BannerExample from './Examples/BannerExample';
 import BottomNavigationBarExample from './Examples/BottomNavigationBarExample';
-import BottomNavigationExample from './Examples/BottomNavigationExample';
 import ButtonExample from './Examples/ButtonExample';
 import CardExample from './Examples/CardExample';
 import CheckboxExample from './Examples/CheckboxExample';
@@ -27,6 +26,7 @@ import ListAccordionExampleGroup from './Examples/ListAccordionGroupExample';
 import ListItemExample from './Examples/ListItemExample';
 import ListSectionExample from './Examples/ListSectionExample';
 import MenuExample from './Examples/MenuExample';
+import NavigationBarExample from './Examples/NavigationBarExample';
 import ProgressBarExample from './Examples/ProgressBarExample';
 import RadioButtonExample from './Examples/RadioButtonExample';
 import RadioButtonGroupExample from './Examples/RadioButtonGroupExample';
@@ -54,7 +54,6 @@ export const mainExamples = {
   Badge: BadgeExample,
   Banner: BannerExample,
   BottomNavigationBarExample,
-  BottomNavigation: BottomNavigationExample,
   Button: ButtonExample,
   Card: CardExample,
   Checkbox: CheckboxExample,
@@ -71,6 +70,7 @@ export const mainExamples = {
   ListSection: ListSectionExample,
   ListItem: ListItemExample,
   Menu: MenuExample,
+  NavigationBar: NavigationBarExample,
   Progressbar: ProgressBarExample,
   Radio: RadioButtonExample,
   RadioGroup: RadioButtonGroupExample,

example/src/Examples/BottomNavigationBarExample.tsx

@@ -11,7 +11,7 @@ import {
   SFSymbol,
   MaterialSymbol,
 } from '@react-navigation/native';
-import { Text, BottomNavigation } from 'react-native-paper';
+import { Text, NavigationBar } from 'react-native-paper';
 
 function HomeScreen() {
   return (
@@ -34,18 +34,16 @@ const BottomNavigationBarExample = createBottomTabNavigator({
     headerShown: false,
   },
   tabBar: ({ navigation, state, descriptors }) => (
-    <BottomNavigation.Bar
+    <NavigationBar
       navigationState={state}
-      onTabPress={({ route, preventDefault }) => {
+      onTabPress={({ route }) => {
         const event = navigation.emit({
           type: 'tabPress',
           target: route.key,
           canPreventDefault: true,
         });
 
-        if (event.defaultPrevented) {
-          preventDefault();
-        } else {
+        if (!event.defaultPrevented) {
           // Custom tab bars must target the tab navigator state.
           navigation.dispatch({
             ...CommonActions.navigate(route.name, route.params),
@@ -119,7 +117,7 @@ const BottomNavigationBarExample = createBottomTabNavigator({
 });
 
 export default Object.assign(BottomNavigationBarExample, {
-  title: 'Bottom Navigation Bar',
+  title: 'Navigation Bar (React Navigation)',
 });
 
 const styles = StyleSheet.create({