diff --git a/docs/docs/guides/01-getting-started.md b/docs/docs/guides/01-getting-started.md index 19fc3c2dea..4e36eaf706 100644 --- a/docs/docs/guides/01-getting-started.md +++ b/docs/docs/guides/01-getting-started.md @@ -12,7 +12,7 @@ title: Getting Started npm install react-native-paper ``` -- From `v5` there is a need to install [react-native-safe-area-context](https://github.com/th3rdwave/react-native-safe-area-context) for handling safe area. +- Install [react-native-safe-area-context](https://github.com/th3rdwave/react-native-safe-area-context) for handling safe area. ```bash npm2yarn npm install react-native-safe-area-context @@ -136,22 +136,19 @@ export default function Main() { ## Customization -You can provide a custom theme to customize the colors, typescales etc. with the `Provider` component. Check the [Material Design 3 default theme](https://github.com/callstack/react-native-paper/blob/main/src/styles/themes/v3/LightTheme.tsx) to see what customization options are supported. +You can provide a custom theme to customize the colors, typescales etc. with the `Provider` component. Check the [default theme](https://github.com/callstack/react-native-paper/blob/main/src/theme/schemes/LightTheme.tsx) to see what customization options are supported. Example: ```js import * as React from 'react'; -import { - MD3LightTheme as DefaultTheme, - PaperProvider, -} from 'react-native-paper'; +import { LightTheme, PaperProvider } from 'react-native-paper'; import App from './src/App'; const theme = { - ...DefaultTheme, + ...LightTheme, colors: { - ...DefaultTheme.colors, + ...LightTheme.colors, primary: 'tomato', secondary: 'yellow', }, diff --git a/docs/docs/guides/02-theming.mdx b/docs/docs/guides/02-theming.mdx index 3b24daf8d4..46431becaa 100644 --- a/docs/docs/guides/02-theming.mdx +++ b/docs/docs/guides/02-theming.mdx @@ -28,7 +28,7 @@ export default function Main() { } ``` -By default React Native Paper will apply the [Material You theme (MD3)](https://github.com/callstack/react-native-paper/blob/main/src/styles/themes/v3/LightTheme.tsx) if no `theme` or `version` prop is passed to the `PaperProvider`. +By default React Native Paper will apply `LightTheme` if no `theme` prop is passed to the `PaperProvider`, automatically switching to `DarkTheme` when the device color scheme is dark. ## Accessing theme properties @@ -62,12 +62,9 @@ export default withTheme(PaymentScreen); You can change the theme prop dynamically and all the components will automatically update to reflect the new theme. -A theme usually contains the following properties: +A theme contains the following properties: - `dark` (`boolean`): whether this is a dark theme or light theme. -- `version`: Material You (MD3); kept for compatibility and normalized to `3` by `PaperProvider` -- `mode` (`'adaptive' | 'exact'`): color mode for dark theme (See [Dark Theme](#dark-theme)). -- `roundness` (`number`): roundness of common elements, such as buttons. - `colors` (`object`): various colors used throughout different elements. > The primary key color is used to derive roles for key components across the UI, such as the FAB, prominent buttons, active states, as well as the tint of elevated surfaces. @@ -143,14 +140,22 @@ A theme usually contains the following properties: - `fontWeight` - `lineHeight` - `fontSize` -- `animation` (`object`) - - `scale` - scale for all animations - -When creating a custom theme, you will need to provide all of these properties. - -If you don't use a custom theme, Paper will automatically turn animations on/off, depending on device settings. - -Otherwise, your custom theme will need to handle it manually, using React Native's [AccessibilityInfo API](https://reactnative.dev/docs/accessibilityinfo). +- `state` (`object`): interaction state opacity layers per the Material Design 3 spec. + - `opacity` - opacities for each interaction state: `hovered` (0.08), `focused` (0.1), `pressed` (0.1), `dragged` (0.16), `disabled` (0.38), `enabled` (1.0) +- `shapes` (`object`): corner radius tokens per the Material Design 3 shape scale. + - `none` · `extraSmall` · `small` · `medium` · `large` · `largeIncreased` · `extraLarge` · `extraLargeIncreased` · `extraExtraLarge` · `full` +- `motion` (`object`): animation tokens: spring physics, easing curves, and durations. + - `spring` - spring stiffness/damping configs for `fast`, `default`, and `slow` speeds, each with `spatial` and `effects` variants + - `easing` - cubic bezier easing curves: `emphasized`, `emphasizedAccelerate`, `emphasizedDecelerate`, `standard`, `standardAccelerate`, `standardDecelerate`, `legacy`, and more + - `duration` - duration milestones in ms: `short1` (50 ms) through `extraLong4` + - `prefersReducedMotion` (`boolean`) - automatically set from device accessibility settings by `PaperProvider` +- `elevation` (`object`): maps elevation level names to their numeric values (`level0`–`level5`). +- `dynamic` (`boolean`, optional): `true` when Android Material You dynamic colors are active. +- `roundness` (`number`): **Deprecated.** Use `theme.shapes.*` instead. +- `animation` (`object`): **Deprecated.** Use `theme.motion.*` instead. + - `scale` - **Deprecated.** Use `theme.motion.prefersReducedMotion` instead. + +`PaperProvider` automatically reflects the device's "Reduce Motion" accessibility setting into `theme.motion.prefersReducedMotion` (and the legacy `theme.animation.scale`). To opt out and handle accessibility yourself, pass `accessibilityAdapters={false}` to `PaperProvider`. ## Extending the theme @@ -158,19 +163,16 @@ Keeping your own properties in the theme is fully supported by our library: ```js import * as React from 'react'; -import { - MD3LightTheme as DefaultTheme, - PaperProvider, -} from 'react-native-paper'; +import { LightTheme, PaperProvider } from 'react-native-paper'; import App from './src/App'; const theme = { - ...DefaultTheme, + ...LightTheme, // Specify custom property myOwnProperty: true, // Specify custom property in nested object colors: { - ...DefaultTheme.colors, + ...LightTheme.colors, myOwnColor: '#BADA55', }, }; @@ -187,7 +189,7 @@ export default function Main() { ## Creating dynamic theme colors Dynamic Color Themes allows for generating two color schemes lightScheme and darkScheme, based on the provided source color. -Created schemes are following the Material Design 3 color system and covering colors structure from the Paper theme. User may generate these schemes using the following tool: +Created schemes follow the Material Design 3 color system and cover the full color structure of the Paper theme. Use the tool below to generate them: @@ -205,14 +207,11 @@ Once we have copied the color schemes from the generated JSON above, we can use ```jsx import * as React from 'react'; -import { - MD3LightTheme as DefaultTheme, - PaperProvider, -} from 'react-native-paper'; +import { LightTheme, PaperProvider } from 'react-native-paper'; import App from './src/App'; const theme = { - ...DefaultTheme, + ...LightTheme, colors: yourGeneratedLightOrDarkScheme.colors, // Copy it from the color codes scheme and then use it here }; @@ -227,12 +226,29 @@ export default function Main() { ### Sync dynamic colors with system colors -React Native Paper provides built-in support for Android dynamic colors through `DynamicLightTheme` and `DynamicDarkTheme`. These themes use React Native's `PlatformColor` API to map all Material Design 3 color roles to Android system colors, so any changes the user makes to their system palette are automatically reflected in the app. +React Native Paper supports Android Material You dynamic colors (wallpaper-seeded colors). The simplest way to enable them is the `dynamicColor` prop on `PaperProvider`: + +```tsx +import { PaperProvider } from 'react-native-paper'; +import App from './src/App'; + +export default function Main() { + return ( + + + + ); +} +``` + +When `dynamicColor` is enabled, `PaperProvider` overlays the Android system colors onto `theme.colors` and sets `theme.dynamic = true`. On unsupported platforms and Android versions below API 31, it silently falls back to the static theme. :::info -Dynamic colors require Android 12 (API 31+). On older Android versions and all other platforms, these themes fall back to the default `LightTheme` / `DarkTheme`. +Dynamic colors require Android 12 (API 31+). On older Android versions and all other platforms, `dynamicColor` has no effect. ::: +Alternatively, you can use the pre-built `DynamicLightTheme` and `DynamicDarkTheme` objects directly. These use React Native's `PlatformColor` API to map all color roles to the system palette: + ```tsx import { useColorScheme } from 'react-native'; import { @@ -255,7 +271,7 @@ export default function Main() { ## Adapting React Navigation theme -The `adaptNavigationTheme` function takes an existing React Navigation theme and returns a React Navigation theme using the colors from Material Design 3. This theme can be passed to `NavigationContainer` so that React Navigation's UI elements have the same color scheme as Paper. +The `adaptNavigationTheme` function takes an existing React Navigation theme and returns a React Navigation theme using Paper's color scheme. Pass the result to `NavigationContainer` so that React Navigation's UI elements match Paper's colors. ```ts adaptNavigationTheme(themes); @@ -306,21 +322,24 @@ Valid `themes` keys are: ```ts // App.tsx -import { NavigationContainer, DefaultTheme } from '@react-navigation/native'; +import { + NavigationContainer, + DefaultTheme as NavigationDefaultTheme, +} from '@react-navigation/native'; import { createStackNavigator } from '@react-navigation/stack'; import { PaperProvider, - MD3LightTheme, + LightTheme, adaptNavigationTheme, } from 'react-native-paper'; const Stack = createStackNavigator(); -const { LightTheme } = adaptNavigationTheme({ - reactNavigationLight: DefaultTheme, +const { LightTheme: NavigationLightTheme } = adaptNavigationTheme({ + reactNavigationLight: NavigationDefaultTheme, }); export default function App() { return ( - - + + @@ -343,29 +362,19 @@ There are two supported ways of overriding the theme: change the built-in schema shape -:::caution -TypeScript support for `withTheme` is currently limited to Material You (MD3) theme only. - - - We are planning to provide a better support of handling custom theme overrides - in future releases. - -::: - ### Simple built-in theme overrides You can provide a `theme` prop with a theme object with the same properties as the default theme: ```js import * as React from 'react'; -import { MD3LightTheme, PaperProvider } from 'react-native-paper'; +import { LightTheme, PaperProvider } from 'react-native-paper'; import App from './src/App'; const theme = { - ...MD3LightTheme, // or MD3DarkTheme - roundness: 2, + ...LightTheme, // or DarkTheme colors: { - ...MD3LightTheme.colors, + ...LightTheme.colors, primary: '#3498db', secondary: '#f1c40f', tertiary: '#a1b2c3', @@ -389,18 +398,18 @@ If you need to modify the built-in theme schema by adding a new property or chan ```ts import * as React from 'react'; -import { MD3LightTheme, PaperProvider } from 'react-native-paper'; +import { LightTheme, PaperProvider } from 'react-native-paper'; import App from './src/App'; const theme = { - ...MD3LightTheme, + ...LightTheme, // Specify a custom property custom: 'property', // Specify a custom property in nested object colors: { - ...MD3LightTheme.colors, + ...LightTheme.colors, brandPrimary: '#fefefe', brandSecondary: 'red', }, @@ -419,18 +428,18 @@ export default function Main() { ```ts import * as React from 'react'; -import { MD3LightTheme, PaperProvider, useTheme } from 'react-native-paper'; +import { LightTheme, PaperProvider, useTheme } from 'react-native-paper'; import App from './src/App'; const theme = { - ...MD3LightTheme, + ...LightTheme, // Specify a custom property custom: 'property', // Specify a custom property in nested object colors: { - ...MD3LightTheme.colors, + ...LightTheme.colors, brandPrimary: '#fefefe', brandSecondary: 'red', }, @@ -466,7 +475,7 @@ export default function HomeScreen() { ## Material Design 3 -React Native Paper ships with Material Design 3 (Material You) only. Customize the default experience by extending `MD3LightTheme` or `MD3DarkTheme` (see [Extending the theme](#extending-the-theme) and [Advanced theme overrides](#advanced-theme-overrides)). +React Native Paper implements Material Design 3 exclusively. Customize the default experience by extending `LightTheme` or `DarkTheme` (see [Extending the theme](#extending-the-theme) and [Advanced theme overrides](#advanced-theme-overrides)). ## Applying a theme to a paper component @@ -509,19 +518,9 @@ 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).
-In contrast to light theme, dark theme by default uses `surface` colour instead of `primary` on large components like `AppBar` or `BottomNavigation`.
-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. - -We are aware that users often use dark theme in their own ways and may not want to use the default dark theme features from the guidelines.
-That's why if you are using dark theme you can switch between two dark theme `mode`s: - -- `exact` where everything is like it was before. `Appbar` and `BottomNavigation` will still use primary colour by default.
-- `adaptive` where we follow [Material design guidelines](https://material.io/design/color/dark-theme.html), the surface will use white overlay with opacity to show elevation, `Appbar` and `BottomNavigation` will use surface colour as a background. - -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. +React Native Paper follows the [Material Design 3 dark theme guidelines](https://m3.material.io/styles/color/dark-theme). Dark surfaces use tonal color overlays derived from the primary color to convey elevation. -Otherwise, your custom theme will need to handle it manually, using React Native's [Appearance API](https://reactnative.dev/docs/appearance). +`PaperProvider` automatically switches between `LightTheme` and `DarkTheme` based on the device color scheme. If you pass a custom `theme` prop, it is used as-is; you can toggle dark mode by changing `theme.dark` or swapping between your own light and dark theme objects. ## Gotchas diff --git a/docs/docs/guides/04-fonts.md b/docs/docs/guides/04-fonts.md index 5e8e435c0a..115418feab 100644 --- a/docs/docs/guides/04-fonts.md +++ b/docs/docs/guides/04-fonts.md @@ -47,15 +47,9 @@ Now, you are able to use `fontFamily` from font files. ## Configuring fonts in ThemeProvider -:::note -Older Material Design 2 platform-split font configuration (`configureFonts` with per-platform `ios` / `android` / `web` keys) is no longer supported. Use the Material Design 3 typescale and `configureFonts` as documented below. -::: - -### Material Design 3 - #### Variants -In the latest version fonts in theme are structured based on the `variant` keys e.g. `displayLarge` or `bodyMedium` which are then used in `Text`'s component throughout the whole library. +Fonts in the theme are structured based on `variant` keys, e.g. `displayLarge` or `bodyMedium`, which are used by `Text` throughout the library. :::info The default `fontFamily` is different per particular platfrom: @@ -317,7 +311,7 @@ If any component uses Paper's `Text` component, without specified variant ```js import * as React from 'react'; -import { configureFonts, MD3LightTheme, PaperProvider } from 'react-native-paper'; +import { configureFonts, LightTheme, PaperProvider } from 'react-native-paper'; import App from './src/App'; const fontConfig = { @@ -335,7 +329,7 @@ const fontConfig = { }; const theme = { - ...MD3LightTheme, + ...LightTheme, fonts: configureFonts({config: fontConfig}), }; @@ -362,7 +356,7 @@ export const Text = customText<'customVariant'>() ```js import * as React from 'react'; -import { configureFonts, MD3LightTheme, PaperProvider } from 'react-native-paper'; +import { configureFonts, LightTheme, PaperProvider } from 'react-native-paper'; import App from './src/App'; const fontConfig = { @@ -374,7 +368,7 @@ const fontConfig = { }; const theme = { - ...MD3LightTheme, + ...LightTheme, fonts: configureFonts({config: fontConfig}), }; @@ -391,7 +385,7 @@ export default function Main() { ```js import * as React from 'react'; -import { configureFonts, MD3LightTheme, PaperProvider } from 'react-native-paper'; +import { configureFonts, LightTheme, PaperProvider } from 'react-native-paper'; import App from './src/App'; const fontConfig = { @@ -399,7 +393,7 @@ const fontConfig = { }; const theme = { - ...MD3LightTheme, + ...LightTheme, fonts: configureFonts({config: fontConfig}), }; diff --git a/docs/docs/guides/08-theming-with-react-navigation.md b/docs/docs/guides/08-theming-with-react-navigation.md index 272b0c08cd..7921da6726 100644 --- a/docs/docs/guides/08-theming-with-react-navigation.md +++ b/docs/docs/guides/08-theming-with-react-navigation.md @@ -11,11 +11,9 @@ But how to make them work together? ## Themes adaptation -### Material Design 3 +React Native Paper uses the Material Design 3 color system, which differs from React Navigation’s default theme shape. -React Native Paper follows the Material Design 3 (Material You) color system, which differs from React Navigation’s default theme shape. - -However, to simplify adapting React Navigation theme colors, to use the ones from React Native Paper, it's worth using a utility called `adaptNavigationTheme` – it accepts navigation-compliant themes in both modes and returns their equivalents adjusted to Material Design 3. +To adapt React Navigation’s theme to use Paper’s colors, use the `adaptNavigationTheme` utility. It accepts navigation-compliant themes and returns equivalents that match Paper’s color scheme. ```ts import { @@ -24,19 +22,17 @@ import { } from '@react-navigation/native'; import { adaptNavigationTheme } from 'react-native-paper'; -const { LightTheme, DarkTheme } = adaptNavigationTheme({ - reactNavigationLight: NavigationDefaultTheme, - reactNavigationDark: NavigationDarkTheme, -}); +const { LightTheme: NavLightTheme, DarkTheme: NavDarkTheme } = + adaptNavigationTheme({ + reactNavigationLight: NavigationDefaultTheme, + reactNavigationDark: NavigationDarkTheme, + }); ``` -Library exports also Material Design 3 themes in both modes: +Library exports themes in both modes: ```js -import { - MD3LightTheme, - MD3DarkTheme, -} from 'react-native-paper'; +import { LightTheme, DarkTheme } from 'react-native-paper'; ``` ## Combining theme objects @@ -110,8 +106,6 @@ To make things easier we can use [deepmerge](https://www.npmjs.com/package/deepm npm install deepmerge ``` -### Material Design 3 - ```js import { NavigationContainer, @@ -119,45 +113,45 @@ import { DefaultTheme as NavigationDefaultTheme, } from '@react-navigation/native'; import { - MD3DarkTheme, - MD3LightTheme, + DarkTheme, + LightTheme, adaptNavigationTheme, } from 'react-native-paper'; import merge from 'deepmerge'; -const { LightTheme, DarkTheme } = adaptNavigationTheme({ - reactNavigationLight: NavigationDefaultTheme, - reactNavigationDark: NavigationDarkTheme, -}); +const { LightTheme: NavLightTheme, DarkTheme: NavDarkTheme } = + adaptNavigationTheme({ + reactNavigationLight: NavigationDefaultTheme, + reactNavigationDark: NavigationDarkTheme, + }); -const CombinedDefaultTheme = merge(MD3LightTheme, LightTheme); -const CombinedDarkTheme = merge(MD3DarkTheme, DarkTheme); +const CombinedDefaultTheme = merge(LightTheme, NavLightTheme); +const CombinedDarkTheme = merge(DarkTheme, NavDarkTheme); ``` Alternatively, we could merge those themes using vanilla JavaScript: -### Material Design 3 - ```js -const { LightTheme, DarkTheme } = adaptNavigationTheme({ - reactNavigationLight: NavigationDefaultTheme, - reactNavigationDark: NavigationDarkTheme, -}); +const { LightTheme: NavLightTheme, DarkTheme: NavDarkTheme } = + adaptNavigationTheme({ + reactNavigationLight: NavigationDefaultTheme, + reactNavigationDark: NavigationDarkTheme, + }); const CombinedDefaultTheme = { - ...MD3LightTheme, ...LightTheme, + ...NavLightTheme, colors: { - ...MD3LightTheme.colors, ...LightTheme.colors, + ...NavLightTheme.colors, }, }; const CombinedDarkTheme = { - ...MD3DarkTheme, ...DarkTheme, + ...NavDarkTheme, colors: { - ...MD3DarkTheme.colors, ...DarkTheme.colors, + ...NavDarkTheme.colors, }, }; ``` diff --git a/docs/docs/guides/09-bottom-navigation.md b/docs/docs/guides/09-bottom-navigation.md index 21776718c9..7ac8e0b17d 100644 --- a/docs/docs/guides/09-bottom-navigation.md +++ b/docs/docs/guides/09-bottom-navigation.md @@ -2,247 +2,8 @@ title: Using BottomNavigation with React Navigation --- -:::caution -The `createMaterialBottomTabNavigator` has been deprecated as of `react-native-paper@5.14.0`. Instead, use `@react-navigation/bottom-tabs` version `7.x` or later, combined with `BottomNavigation.Bar` to achieve a Material Design look. +:::danger Removed in v6 +`createMaterialBottomTabNavigator` has been removed from React Native Paper as of v6. Use `@react-navigation/bottom-tabs` (v7+) together with `BottomNavigation.Bar` to achieve the same look. -For implementation details, see the [dedicated example](https://callstack.github.io/react-native-paper/docs/components/BottomNavigation/BottomNavigationBar#with-react-navigation). +See the [BottomNavigation.Bar documentation](https://callstack.github.io/react-native-paper/docs/components/BottomNavigation/BottomNavigationBar#with-react-navigation) for a complete integration example. ::: - -A material-design themed tab bar on the bottom of the screen that lets you switch between different routes with animation. Routes are lazily initialized - their screen components are not mounted until they are first focused. - -This wraps the [`BottomNavigation`](https://callstack.github.io/react-native-paper/docs/components/BottomNavigation/) component from `react-native-paper`, however if you [configure the Babel plugin](https://callstack.github.io/react-native-paper/docs/guides/getting-started/), it won't include the whole library in your bundle. - - - -:::info -To use this navigator, ensure that you have [`@react-navigation/native` and its dependencies (follow this guide)](https://reactnavigation.org/docs/getting-started): -::: - -> 👉 For a complete example please visit `createMaterialBottomTabNavigator` [snack](https://snack.expo.dev/@react-native-paper/creatematerialbottomtabnavigator) - -## API Definition - -To use this tab navigator, import it from `react-native-paper/react-navigation`: - -```js -import { createMaterialBottomTabNavigator } from 'react-native-paper/react-navigation'; - -const Tab = createMaterialBottomTabNavigator(); - -function MyTabs() { - return ( - - - - - ); -} -``` - -> 👉 For a complete usage guide please visit [Tab Navigation](https://reactnavigation.org/docs/tab-based-navigation/) - -### Props - -The `Tab.Navigator` component accepts following props: - -#### `id` - -Optional unique ID for the navigator. This can be used with [`navigation.getParent`](https://reactnavigation.org/docs/navigation-prop#getparent) to refer to this navigator in a child navigator. - -#### `initialRouteName` - -The name of the route to render on first load of the navigator. - -#### `screenOptions` - -Default options to use for the screens in the navigator. - -#### `backBehavior` - -This controls what happens when `goBack` is called in the navigator. This includes pressing the device's back button or back gesture on Android. - -It supports the following values: - -- `firstRoute` - return to the first screen defined in the navigator (default) -- `initialRoute` - return to initial screen passed in `initialRouteName` prop, if not passed, defaults to the first screen -- `order` - return to screen defined before the focused screen -- `history` - return to last visited screen in the navigator; if the same screen is visited multiple times, the older entries are dropped from the history -- `none` - do not handle back button - -#### `shifting` - -Whether the shifting style is used, the active tab icon shifts up to show the label and the inactive tabs won't have a label. - -By default, this is `true` when you have more than 3 tabs. Pass `shifting={false}` to explicitly disable this animation, or `shifting={true}` to always use this animation. - -#### `labeled` - -Whether to show labels in tabs. When `false`, only icons will be displayed. - -#### `activeColor` - -Custom color for icon and label in the active tab. - -#### `inactiveColor` - -Custom color for icon and label in the inactive tab. - -#### `barStyle` - -Style for the bottom navigation bar. You can pass custom background color here: - -```js - - {/* ... */} - -``` - -If you have a translucent navigation bar on Android, you can also set a bottom padding here: - -```js - - {/* ... */} - -``` - -#### `theme` - -Enables the customization of default theme attributes (e.g. colors) or facilitates the utilization of a personalized custom theme. - -### Options - -The following [options](https://reactnavigation.org/docs/screen-options) can be used to configure the screens in the navigator: - -#### `title` - -Generic title that can be used as a fallback for `headerTitle` and `tabBarLabel`. - -#### `tabBarIcon` - -Function that given `{ focused: boolean, color: string }` returns a React.Node, to display in the tab bar. - -#### `tabBarColor`
In v5.x works only with theme version 2.
- -Color for the tab bar when the tab corresponding to the screen is active. Used for the ripple effect. This is only supported when `shifting` is `true`. - -#### `tabBarLabel` - -Title string of a tab displayed in the tab bar. When undefined, scene `title` is used. To hide, see `labeled` option in the previous section. - -#### `tabBarBadge` - -Badge to show on the tab icon, can be `true` to show a dot, `string` or `number` to show text. - -#### `tabBarAccessibilityLabel` - -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. - -#### `tabBarTestID` - -ID to locate this tab button in tests. - -### Events - -The navigator can [emit events](https://reactnavigation.org/docs/navigation-events) on certain actions. Supported events are: - -#### `tabPress` - -This event is fired when the user presses the tab button for the current screen in the tab bar. By default a tab press does several things: - -- If the tab is not focused, tab press will focus that tab -- If the tab is already focused: - - If the screen for the tab renders a scroll view, you can use [`useScrollToTop`](https://reactnavigation.org/docs/use-scroll-to-top) to scroll it to top - - If the screen for the tab renders a stack navigator, a `popToTop` action is performed on the stack - -To prevent the default behavior, you can call `event.preventDefault`: - -```js -React.useEffect(() => { - const unsubscribe = navigation.addListener('tabPress', (e) => { - // Prevent default behavior - - e.preventDefault(); - // Do something manually - // ... - }); - - return unsubscribe; -}, [navigation]); -``` - -### Helpers - -The tab navigator adds the following methods to the navigation prop: - -#### `jumpTo` - -Navigates to an existing screen in the tab navigator. The method accepts following arguments: - -- `name` - _string_ - Name of the route to jump to. -- `params` - _object_ - Screen params to pass to the destination route. - - - -```js -navigation.jumpTo('Profile', { name: 'Michaś' }); -``` - -## Example - -```js -import { createMaterialBottomTabNavigator } from 'react-native-paper/react-navigation'; -import MaterialDesignIcons from '@react-native-vector-icons/material-design-icons'; - -const Tab = createMaterialBottomTabNavigator(); - -function MyTabs() { - return ( - - ( - - ), - }} - /> - ( - - ), - }} - /> - ( - - ), - }} - /> - - ); -} -```