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 a151e58353..b2c77c998d 100644 --- a/docs/docs/guides/09-bottom-navigation.md +++ b/docs/docs/guides/09-bottom-navigation.md @@ -2,110 +2,10 @@ title: Using BottomNavigation with React Navigation --- -:::caution -`createMaterialBottomTabNavigator` was deprecated in `react-native-paper@5.14.0` and removed in `react-native-paper@6.0.0`. Use [`@react-navigation/bottom-tabs`](https://reactnavigation.org/docs/bottom-tab-navigator) (v7+) with [`BottomNavigation.Bar`](https://callstack.github.io/react-native-paper/docs/components/BottomNavigation/BottomNavigationBar) instead. -::: - -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). +For Material Design bottom tabs in React Navigation, render [`BottomNavigation.Bar`](https://callstack.github.io/react-native-paper/docs/components/BottomNavigation/BottomNavigationBar) as the `tabBar` of [`@react-navigation/bottom-tabs`](https://reactnavigation.org/docs/bottom-tab-navigator) (v7+). See the [integration example](https://callstack.github.io/react-native-paper/docs/components/BottomNavigation/BottomNavigationBar#with-react-navigation). -:::info -Install [`@react-navigation/native`](https://reactnavigation.org/docs/getting-started) and [`@react-navigation/bottom-tabs@^7`](https://reactnavigation.org/docs/bottom-tab-navigator) first. +:::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. ::: - -## Quick example - -Pass a `BottomNavigation.Bar` to the navigator's `tabBar` prop. The bar reads navigation state and dispatches `tabPress` events back: - -```jsx -import { CommonActions } from '@react-navigation/native'; -import { createBottomTabNavigator } from '@react-navigation/bottom-tabs'; -import { BottomNavigation } from 'react-native-paper'; -import MaterialCommunityIcons from '@expo/vector-icons/MaterialCommunityIcons'; - -const Tab = createBottomTabNavigator(); - -function MyTabs() { - return ( - ( - { - const event = navigation.emit({ - type: 'tabPress', - target: route.key, - canPreventDefault: true, - }); - if (event.defaultPrevented) { - preventDefault(); - } else { - navigation.dispatch({ - ...CommonActions.navigate(route.name, route.params), - target: state.key, - }); - } - }} - renderIcon={({ route, focused, color }) => - descriptors[route.key].options.tabBarIcon?.({ - focused, - color, - size: 24, - }) ?? null - } - getLabelText={({ route }) => { - const { options } = descriptors[route.key]; - return typeof options.tabBarLabel === 'string' - ? options.tabBarLabel - : typeof options.title === 'string' - ? options.title - : route.name; - }} - /> - )} - > - ( - - ), - }} - /> - ( - - ), - }} - /> - - ); -} -``` - -## References - -- [`BottomNavigation.Bar` props](https://callstack.github.io/react-native-paper/docs/components/BottomNavigation/BottomNavigationBar): `activeColor`, `inactiveColor`, `shifting`, `labeled`, `barStyle`, `theme`, badges. -- [`BottomNavigation.Bar` example](https://callstack.github.io/react-native-paper/docs/components/BottomNavigation/BottomNavigationBar#with-react-navigation): static-config and dynamic-tree variants. -- [React Navigation bottom-tabs](https://reactnavigation.org/docs/bottom-tab-navigator): navigator props, screen options (`tabBarIcon`, `tabBarLabel`, `tabBarBadge`), `tabPress` events, `jumpTo` helper. - -## Migration - -| Old (removed) | New | -|---|---| -| `createMaterialBottomTabNavigator()` | `createBottomTabNavigator()` from `@react-navigation/bottom-tabs` | -| `` | Pass the same props to `` inside `tabBar` | -| `options.tabBarIcon` / `tabBarLabel` / `tabBarBadge` | Same names; read via `descriptors[route.key].options` in `renderIcon` / `getLabelText` | -| `options.tabBarColor` (theme v2) | Removed. MD3 uses tonal surface colors. | -| `navigation.jumpTo(name, params)` | Same. Provided by `@react-navigation/bottom-tabs`. | -| `tabPress` event | Same. Emitted by `@react-navigation/bottom-tabs`. |