From b237dd15bb7fe9b9d83c212b1a93f95bbc7ea284 Mon Sep 17 00:00:00 2001 From: lukewalczak Date: Thu, 15 May 2025 09:51:28 +0200 Subject: [PATCH 1/3] refactor: remove deprecated and renamed annotations --- example/src/Examples/Dialogs/DialogWithIcon.tsx | 2 +- src/components/Appbar/AppbarContent.tsx | 10 ---------- src/components/BottomNavigation/BottomNavigation.tsx | 9 ++------- .../BottomNavigation/BottomNavigationBar.tsx | 4 ++-- src/components/Button/Button.tsx | 5 ----- src/components/Divider.tsx | 3 --- src/components/Drawer/DrawerCollapsedItem.tsx | 2 -- src/components/FAB/FAB.tsx | 6 ------ src/components/IconButton/IconButton.tsx | 2 -- src/components/Menu/MenuItem.tsx | 2 -- src/components/TextInput/Adornment/TextInputIcon.tsx | 1 - 11 files changed, 5 insertions(+), 41 deletions(-) diff --git a/example/src/Examples/Dialogs/DialogWithIcon.tsx b/example/src/Examples/Dialogs/DialogWithIcon.tsx index 3a0c5f7cfe..1875de5e60 100644 --- a/example/src/Examples/Dialogs/DialogWithIcon.tsx +++ b/example/src/Examples/Dialogs/DialogWithIcon.tsx @@ -24,7 +24,7 @@ const DialogWithIcon = ({ - diff --git a/src/components/Appbar/AppbarContent.tsx b/src/components/Appbar/AppbarContent.tsx index 39318c26a2..406118a03a 100644 --- a/src/components/Appbar/AppbarContent.tsx +++ b/src/components/Appbar/AppbarContent.tsx @@ -39,16 +39,6 @@ export type Props = $RemoveChildren & { * Reference for the title. */ titleRef?: React.RefObject; - /** - * @deprecated Deprecated in v5.x - * Text for the subtitle. - */ - subtitle?: React.ReactNode; - /** - * @deprecated Deprecated in v5.x - * Style for the subtitle. - */ - subtitleStyle?: StyleProp; /** * Function to execute on press. */ diff --git a/src/components/BottomNavigation/BottomNavigation.tsx b/src/components/BottomNavigation/BottomNavigation.tsx index 9355461ae3..18e49fe09c 100644 --- a/src/components/BottomNavigation/BottomNavigation.tsx +++ b/src/components/BottomNavigation/BottomNavigation.tsx @@ -26,10 +26,6 @@ export type BaseRoute = { focusedIcon?: IconSource; unfocusedIcon?: IconSource; badge?: string | number | boolean; - /** - * @deprecated In v5.x works only with theme version 2. - */ - color?: string; accessibilityLabel?: string; testID?: string; lazy?: boolean; @@ -81,9 +77,8 @@ export type Props = { * * - `key`: a unique key to identify the route (required) * - `title`: title of the route to use as the tab label - * - `focusedIcon`: icon to use as the focused tab icon, can be a string, an image source or a react component @renamed Renamed from 'icon' to 'focusedIcon' in v5.x - * - `unfocusedIcon`: icon to use as the unfocused tab icon, can be a string, an image source or a react component @supported Available in v5.x with theme version 3 - * - `color`: color to use as background color for shifting bottom navigation @deprecatedProperty In v5.x works only with theme version 2. + * - `focusedIcon`: icon to use as the focused tab icon, can be a string, an image source or a react component + * - `unfocusedIcon`: icon to use as the unfocused tab icon, can be a string, an image source or a react component * - `badge`: badge to show on the tab icon, can be `true` to show a dot, `string` or `number` to show text. * - `accessibilityLabel`: accessibility label for the tab button * - `testID`: test id for the tab button diff --git a/src/components/BottomNavigation/BottomNavigationBar.tsx b/src/components/BottomNavigation/BottomNavigationBar.tsx index 9d753e4ec8..2f298c455f 100644 --- a/src/components/BottomNavigation/BottomNavigationBar.tsx +++ b/src/components/BottomNavigation/BottomNavigationBar.tsx @@ -88,8 +88,8 @@ export type Props = { * * - `key`: a unique key to identify the route (required) * - `title`: title of the route to use as the tab label - * - `focusedIcon`: icon to use as the focused tab icon, can be a string, an image source or a react component @renamed Renamed from 'icon' to 'focusedIcon' in v5.x - * - `unfocusedIcon`: icon to use as the unfocused tab icon, can be a string, an image source or a react component @supported Available in v5.x with theme version 3 + * - `focusedIcon`: icon to use as the focused tab icon, can be a string, an image source or a react component + * - `unfocusedIcon`: icon to use as the unfocused tab icon, can be a string, an image source or a react component * - `badge`: badge to show on the tab icon, can be `true` to show a dot, `string` or `number` to show text. * - `accessibilityLabel`: accessibility label for the tab button * - `testID`: test id for the tab button diff --git a/src/components/Button/Button.tsx b/src/components/Button/Button.tsx index e82df10782..e44e08e335 100644 --- a/src/components/Button/Button.tsx +++ b/src/components/Button/Button.tsx @@ -53,11 +53,6 @@ export type Props = $Omit, 'mode'> & { * Use a compact look, useful for `text` buttons in a row. */ compact?: boolean; - /** - * @deprecated Deprecated in v5.x - use `buttonColor` or `textColor` instead. - * Custom text color for flat button, or background color for contained button. - */ - color?: string; /** * Custom button's background color. */ diff --git a/src/components/Divider.tsx b/src/components/Divider.tsx index ebd3b42b6d..4545997ee5 100644 --- a/src/components/Divider.tsx +++ b/src/components/Divider.tsx @@ -6,17 +6,14 @@ import type { $RemoveChildren, ThemeProp } from '../types'; export type Props = $RemoveChildren & { /** - * @renamed Renamed from 'inset' to 'leftInset` in v5.x * Whether divider has a left inset. */ leftInset?: boolean; /** - * @supported Available in v5.x with theme version 3 * Whether divider has a horizontal inset on both sides. */ horizontalInset?: boolean; /** - * @supported Available in v5.x with theme version 3 * Whether divider should be bolded. */ bold?: boolean; diff --git a/src/components/Drawer/DrawerCollapsedItem.tsx b/src/components/Drawer/DrawerCollapsedItem.tsx index 303a1db4fd..92a869bb82 100644 --- a/src/components/Drawer/DrawerCollapsedItem.tsx +++ b/src/components/Drawer/DrawerCollapsedItem.tsx @@ -32,12 +32,10 @@ export type Props = React.ComponentPropsWithRef & { */ disabled?: boolean; /** - * @renamed Renamed from 'icon' to 'focusedIcon' in v5.x * Icon to use as the focused destination icon, can be a string, an image source or a react component */ focusedIcon?: IconSource; /** - * @renamed Renamed from 'icon' to 'focusedIcon' in v5.x * Icon to use as the unfocused destination icon, can be a string, an image source or a react component */ unfocusedIcon?: IconSource; diff --git a/src/components/FAB/FAB.tsx b/src/components/FAB/FAB.tsx index 8de132638f..f74a4e033c 100644 --- a/src/components/FAB/FAB.tsx +++ b/src/components/FAB/FAB.tsx @@ -69,12 +69,6 @@ export type Props = $Omit<$RemoveChildren, 'mode'> & { * Whether an icon change is animated. */ animated?: boolean; - /** - * @deprecated Deprecated in v.5x - use prop size="small". - * - * Whether FAB is mini-sized, used to create visual continuity with other elements. This has no effect if `label` is specified. - */ - small?: boolean; /** * Custom color for the icon and label of the `FAB`. */ diff --git a/src/components/IconButton/IconButton.tsx b/src/components/IconButton/IconButton.tsx index c2f3105876..13ca1aecb6 100644 --- a/src/components/IconButton/IconButton.tsx +++ b/src/components/IconButton/IconButton.tsx @@ -29,12 +29,10 @@ export type Props = Omit<$RemoveChildren, 'style'> & { */ icon: IconSource; /** - * @supported Available in v5.x with theme version 3 * Mode of the icon button. By default there is no specified mode - only pressable icon will be rendered. */ mode?: IconButtonMode; /** - * @renamed Renamed from 'color' to 'iconColor' in v5.x * Color of the icon. */ iconColor?: string; diff --git a/src/components/Menu/MenuItem.tsx b/src/components/Menu/MenuItem.tsx index f172fb4bb6..7d4da087eb 100644 --- a/src/components/Menu/MenuItem.tsx +++ b/src/components/Menu/MenuItem.tsx @@ -31,8 +31,6 @@ export type Props = { */ title: React.ReactNode; /** - * @renamed Renamed from 'icon' to 'leadingIcon' in v5.x - * * Leading icon to display for the `MenuItem`. */ leadingIcon?: IconSource; diff --git a/src/components/TextInput/Adornment/TextInputIcon.tsx b/src/components/TextInput/Adornment/TextInputIcon.tsx index f9c4d0291d..39e7861168 100644 --- a/src/components/TextInput/Adornment/TextInputIcon.tsx +++ b/src/components/TextInput/Adornment/TextInputIcon.tsx @@ -20,7 +20,6 @@ export type Props = $Omit< 'icon' | 'theme' | 'color' | 'iconColor' > & { /** - * @renamed Renamed from 'name' to 'icon` in v5.x * Icon to show. */ icon: IconSource; From c2884a6dd597358e6d95f98b14a31e40472018e5 Mon Sep 17 00:00:00 2001 From: lukewalczak Date: Thu, 15 May 2025 09:54:26 +0200 Subject: [PATCH 2/3] refactor: remove react-navigation directory --- docs/docs/guides/09-bottom-navigation.md | 248 ------------------ react-navigation/package.json | 6 - src/index.tsx | 6 - src/react-navigation/__tests__/index.test.tsx | 44 ---- src/react-navigation/index.tsx | 19 -- .../createMaterialBottomTabNavigator.tsx | 76 ------ src/react-navigation/types.tsx | 126 --------- .../views/MaterialBottomTabView.tsx | 139 ---------- 8 files changed, 664 deletions(-) delete mode 100644 docs/docs/guides/09-bottom-navigation.md delete mode 100644 react-navigation/package.json delete mode 100644 src/react-navigation/__tests__/index.test.tsx delete mode 100644 src/react-navigation/index.tsx delete mode 100644 src/react-navigation/navigators/createMaterialBottomTabNavigator.tsx delete mode 100644 src/react-navigation/types.tsx delete mode 100644 src/react-navigation/views/MaterialBottomTabView.tsx diff --git a/docs/docs/guides/09-bottom-navigation.md b/docs/docs/guides/09-bottom-navigation.md deleted file mode 100644 index 21776718c9..0000000000 --- a/docs/docs/guides/09-bottom-navigation.md +++ /dev/null @@ -1,248 +0,0 @@ ---- -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. - -For implementation details, see the [dedicated example](https://callstack.github.io/react-native-paper/docs/components/BottomNavigation/BottomNavigationBar#with-react-navigation). -::: - -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 ( - - ( - - ), - }} - /> - ( - - ), - }} - /> - ( - - ), - }} - /> - - ); -} -``` diff --git a/react-navigation/package.json b/react-navigation/package.json deleted file mode 100644 index e21ec26893..0000000000 --- a/react-navigation/package.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "main": "../lib/commonjs/react-navigation/index", - "module": "../lib/module/react-navigation/index", - "react-native": "../src/react-navigation/index", - "types": "../lib/typescript/react-navigation/index" -} diff --git a/src/index.tsx b/src/index.tsx index b3949e865d..03c816ca42 100644 --- a/src/index.tsx +++ b/src/index.tsx @@ -138,11 +138,5 @@ export type { Props as TextProps } from './components/Typography/Text'; export type { Props as SegmentedButtonsProps } from './components/SegmentedButtons/SegmentedButtons'; export type { Props as ListImageProps } from './components/List/ListImage'; export type { Props as TooltipProps } from './components/Tooltip/Tooltip'; -export type { - MaterialBottomTabNavigationEventMap, - MaterialBottomTabNavigationOptions, - MaterialBottomTabNavigationProp, - MaterialBottomTabScreenProps, -} from './react-navigation'; export type { Theme, ThemeBase, Elevation, TypescaleKey } from './types'; diff --git a/src/react-navigation/__tests__/index.test.tsx b/src/react-navigation/__tests__/index.test.tsx deleted file mode 100644 index a04495639d..0000000000 --- a/src/react-navigation/__tests__/index.test.tsx +++ /dev/null @@ -1,44 +0,0 @@ -import * as React from 'react'; -import { Button, Text, View } from 'react-native'; - -import { NavigationContainer, ParamListBase } from '@react-navigation/native'; -import { fireEvent, render } from '@testing-library/react-native'; - -import PaperProvider from '../../core/PaperProvider'; -import { - createMaterialBottomTabNavigator, - MaterialBottomTabScreenProps, -} from '../index'; - -it('renders a material bottom tab navigator with screens', async () => { - const Test = ({ - route, - navigation, - }: MaterialBottomTabScreenProps) => ( - - Screen {route.name} - - ); + return ; } ``` @@ -616,22 +486,6 @@ export default function FancyButton(props) { Now you can use your `FancyButton` component everywhere instead of using `Button` from Paper. -## 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. - -Otherwise, your custom theme will need to handle it manually, using React Native's [Appearance API](https://reactnative.dev/docs/appearance). - ## Gotchas The `PaperProvider` exposes the theme to the components via [React's context API](https://reactjs.org/docs/context.html), which means that the component must be in the same tree as the `PaperProvider`. Some React Native components will render a different tree such as a `Modal`, in which case the components inside the `Modal` won't be able to access the theme. The work around is to get the theme using the `withTheme` HOC and pass it down to the components as props, or expose it again with the exported `ThemeProvider` component. diff --git a/docs/docs/guides/04-fonts.md b/docs/docs/guides/04-fonts.md index 60d3c6e457..ad25f4fcf9 100644 --- a/docs/docs/guides/04-fonts.md +++ b/docs/docs/guides/04-fonts.md @@ -8,143 +8,45 @@ title: Fonts The easiest way to install custom fonts to your RN project is do as follows: - 1. Define path to assets directory with fonts in project: +1. Define path to assets directory with fonts in project: - Example: +Example: - ```js - module.exports = { - ... - assets: [ - './assets/fonts' - ], - ``` +```js + module.exports = { + ... + assets: [ + './assets/fonts' + ], +``` :::note `fonts` is a folder with `.ttf` files ::: - 2. Place your font files in your assets directory. +2. Place your font files in your assets directory. - 3. Link font files, using the following command in the terminal: +3. Link font files, using the following command in the terminal: - * React Native `>= 0.69`: +- React Native `>= 0.69`: - ```sh - npx react-native-asset - ``` - - * React Native `< 0.69`: +```sh +npx react-native-asset +``` - ```sh - npx react-native link - ``` +- React Native `< 0.69`: +```sh +npx react-native link +``` - 4. Restart your project to refresh changes. +4. Restart your project to refresh changes. Now, you are able to use `fontFamily` from font files. ## Configuring fonts in ThemeProvider -### Material Design 2 - -#### Using `configureFonts` helper - -To create a custom font, prepare a `fontConfig` object where fonts are divided by platforms. After that, you have to: - -* pass the `fontConfig` into `configureFonts` params object property called `config` -* set the params object property `isV3` to `false`. - -The `fontConfig` object accepts `ios`, `android`, `macos`, `windows`, `web`, and `native`. Use these to override fonts on particular platforms. - -:::info -At a minimum, you need to explicitly pass fonts for `android`, `ios`, and `web`. -::: - -```js -import * as React from 'react'; -import { configureFonts, MD2LightTheme, PaperProvider } from 'react-native-paper'; -import App from './src/App'; - -const fontConfig = { - web: { - regular: { - fontFamily: 'sans-serif', - fontWeight: 'normal', - }, - medium: { - fontFamily: 'sans-serif-medium', - fontWeight: 'normal', - }, - light: { - fontFamily: 'sans-serif-light', - fontWeight: 'normal', - }, - thin: { - fontFamily: 'sans-serif-thin', - fontWeight: 'normal', - }, - }, - ios: { - regular: { - fontFamily: 'sans-serif', - fontWeight: 'normal', - }, - medium: { - fontFamily: 'sans-serif-medium', - fontWeight: 'normal', - }, - light: { - fontFamily: 'sans-serif-light', - fontWeight: 'normal', - }, - thin: { - fontFamily: 'sans-serif-thin', - fontWeight: 'normal', - }, - }, - android: { - regular: { - fontFamily: 'sans-serif', - fontWeight: 'normal', - }, - medium: { - fontFamily: 'sans-serif-medium', - fontWeight: 'normal', - }, - light: { - fontFamily: 'sans-serif-light', - fontWeight: 'normal', - }, - thin: { - fontFamily: 'sans-serif-thin', - fontWeight: 'normal', - }, - } -}; - -const theme = { - ...MD2LightTheme, - fonts: configureFonts({config: fontConfig, isV3: false}), -}; - -export default function Main() { - return ( - - - - ); -} -``` - -:::tip -If you're using TypeScript use `as const` when defining `fontConfig`. -::: - -### Material Design 3 - -#### Variants +### 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. @@ -158,234 +60,235 @@ Platform.select({ default: 'sans-serif', // and 'sans-serif-medium' for `fontWeight:"500"` }), ``` + ::: -* #### Display +- #### Display
- ```json - "displaySmall": { - "fontFamily": "Font", - "fontSize": 36, - "fontWeight": "400", - "letterSpacing": 0, - "lineHeight": 44, - } - ``` +```json +"displaySmall": { + "fontFamily": "Font", + "fontSize": 36, + "fontWeight": "400", + "letterSpacing": 0, + "lineHeight": 44, +} +```
- ```json - "displayMedium": { - "fontFamily": "Font", - "fontSize": 45, - "fontWeight": "400", - "letterSpacing": 0, - "lineHeight": 52, - } - ``` +```json +"displayMedium": { + "fontFamily": "Font", + "fontSize": 45, + "fontWeight": "400", + "letterSpacing": 0, + "lineHeight": 52, +} +```
- ```json - "displayLarge": { - "fontFamily": "Font", - "fontSize": 57, - "fontWeight": "400", - "letterSpacing": 0, - "lineHeight": 64, - } - ``` +```json +"displayLarge": { + "fontFamily": "Font", + "fontSize": 57, + "fontWeight": "400", + "letterSpacing": 0, + "lineHeight": 64, +} +```
-* #### Headline +- #### Headline
- ```json - "headlineSmall": { - "fontFamily": "Font", - "fontSize": 24, - "fontWeight": "400", - "letterSpacing": 0, - "lineHeight": 32, - } - ``` +```json +"headlineSmall": { + "fontFamily": "Font", + "fontSize": 24, + "fontWeight": "400", + "letterSpacing": 0, + "lineHeight": 32, +} +```
- ```json - "headlineMedium": { - "fontFamily": "Font", - "fontSize": 28, - "fontWeight": "400", - "letterSpacing": 0, - "lineHeight": 36, - } - ``` +```json +"headlineMedium": { + "fontFamily": "Font", + "fontSize": 28, + "fontWeight": "400", + "letterSpacing": 0, + "lineHeight": 36, +} +```
- ```json - "headlineLarge": { - "fontFamily": "Font", - "fontSize": 32, - "fontWeight": "400", - "letterSpacing": 0, - "lineHeight": 40, - } - ``` +```json +"headlineLarge": { + "fontFamily": "Font", + "fontSize": 32, + "fontWeight": "400", + "letterSpacing": 0, + "lineHeight": 40, +} +```
-* #### Title +- #### Title
- ```json - "titleSmall": { - "fontFamily": "Font", - "fontSize": 14, - "fontWeight": "500", - "letterSpacing": 0.1, - "lineHeight": 20, - } - ``` +```json +"titleSmall": { + "fontFamily": "Font", + "fontSize": 14, + "fontWeight": "500", + "letterSpacing": 0.1, + "lineHeight": 20, +} +```
- ```json - "titleMedium": { - "fontFamily": "Font", - "fontSize": 16, - "fontWeight": "500", - "letterSpacing": 0.15, - "lineHeight": 24, - } - ``` +```json +"titleMedium": { + "fontFamily": "Font", + "fontSize": 16, + "fontWeight": "500", + "letterSpacing": 0.15, + "lineHeight": 24, +} +```
- ```json - "titleLarge": { - "fontFamily": "Font", - "fontSize": 22, - "fontWeight": "400", - "letterSpacing": 0, - "lineHeight": 28, - } - ``` +```json +"titleLarge": { + "fontFamily": "Font", + "fontSize": 22, + "fontWeight": "400", + "letterSpacing": 0, + "lineHeight": 28, +} +```
-* #### Label +- #### Label
- ```json - "labelSmall": { - "fontFamily": "Font", - "fontSize": 11, - "fontWeight": "500", - "letterSpacing": 0.5, - "lineHeight": 16, - } - ``` +```json +"labelSmall": { + "fontFamily": "Font", + "fontSize": 11, + "fontWeight": "500", + "letterSpacing": 0.5, + "lineHeight": 16, +} +```
- ```json - "labelMedium": { - "fontFamily": "Font", - "fontSize": 12, - "fontWeight": "500", - "letterSpacing": 0.5, - "lineHeight": 16, - } - ``` +```json +"labelMedium": { + "fontFamily": "Font", + "fontSize": 12, + "fontWeight": "500", + "letterSpacing": 0.5, + "lineHeight": 16, +} +```
- ```json - "labelLarge": { - "fontFamily": "Font", - "fontSize": 14, - "fontWeight": "500", - "letterSpacing": 0.1, - "lineHeight": 20, - } - ``` +```json +"labelLarge": { + "fontFamily": "Font", + "fontSize": 14, + "fontWeight": "500", + "letterSpacing": 0.1, + "lineHeight": 20, +} +```
-* #### Body +- #### Body
- ```json - "bodySmall": { - "fontFamily": "Font", - "fontSize": 12, - "fontWeight": "400", - "letterSpacing": 0.4, - "lineHeight": 16, - } - ``` +```json +"bodySmall": { + "fontFamily": "Font", + "fontSize": 12, + "fontWeight": "400", + "letterSpacing": 0.4, + "lineHeight": 16, +} +```
- ```json - "bodyMedium": { - "fontFamily": "Font", - "fontSize": 14, - "fontWeight": "400", - "letterSpacing": 0.25, - "lineHeight": 20, - } - ``` +```json +"bodyMedium": { + "fontFamily": "Font", + "fontSize": 14, + "fontWeight": "400", + "letterSpacing": 0.25, + "lineHeight": 20, +} +```
- ```json - "bodyLarge": { - "fontFamily": "Font", - "fontSize": 16, - "fontWeight": "400", - "letterSpacing": 0.15, - "lineHeight": 24, - } - ``` +```json +"bodyLarge": { + "fontFamily": "Font", + "fontSize": 16, + "fontWeight": "400", + "letterSpacing": 0.15, + "lineHeight": 24, +} +```
@@ -400,15 +303,16 @@ If any component uses Paper's `Text` component, without specified variant "letterSpacing": 0, }, ``` + ::: -#### Using `configureFonts` helper +### Using `configureFonts` helper -* If there is a need to create a custom font variant, prepare its config object including required all fonts properties. After that, defined `fontConfig` has to be passed under the `variant` name as `config` into the params object: +- If there is a need to create a custom font variant, prepare its config object including required all fonts properties. After that, defined `fontConfig` has to be passed under the `variant` name as `config` into the params object: ```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 = { @@ -422,12 +326,12 @@ const fontConfig = { letterSpacing: 0.5, lineHeight: 22, fontSize: 20, - } + }, }; const theme = { - ...MD3LightTheme, - fonts: configureFonts({config: fontConfig}), + ...LightTheme, + fonts: configureFonts({ config: fontConfig }), }; export default function Main() { @@ -442,18 +346,17 @@ export default function Main() { If you're using TypeScript you will need to create a custom `Text` component which accepts your custom variants: ```typescript -import { customText } from 'react-native-paper' +import { customText } from 'react-native-paper'; // Use this instead of importing `Text` from `react-native-paper` -export const Text = customText<'customVariant'>() +export const Text = customText<'customVariant'>(); ``` - -* In order to override one of the available `variant`'s font properties, pass the modified `fontConfig` under specific `variant` name as `config` into the params object: +- In order to override one of the available `variant`'s font properties, pass the modified `fontConfig` under specific `variant` name as `config` into the params object: ```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 = { @@ -461,12 +364,12 @@ const fontConfig = { letterSpacing: 0.5, lineHeight: 22, fontSize: 20, - } + }, }; const theme = { - ...MD3LightTheme, - fonts: configureFonts({config: fontConfig}), + ...LightTheme, + fonts: configureFonts({ config: fontConfig }), }; export default function Main() { @@ -478,20 +381,20 @@ export default function Main() { } ``` -* However, if you just want to override any font property e.g. `fontFamily` or `letterSpacing` for all variants, you can pass the `fontConfig` as a `config` into the params object without specifying variant name: +- However, if you just want to override any font property e.g. `fontFamily` or `letterSpacing` for all variants, you can pass the `fontConfig` as a `config` into the params object without specifying variant name: ```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 = { - fontFamily: 'NotoSans' + fontFamily: 'NotoSans', }; const theme = { - ...MD3LightTheme, - fonts: configureFonts({config: fontConfig}), + ...LightTheme, + fonts: configureFonts({ config: fontConfig }), }; export default function Main() { @@ -503,17 +406,16 @@ export default function Main() { } ``` - ## Variable fonts -Although React Native Paper supports `fontWeight` and `fontStyle` properties, there are multiple limitations to custom -fonts in React Native. Using custom [variable fonts](https://fonts.google.com/knowledge/introducing_type/introducing_variable_fonts) +Although React Native Paper supports `fontWeight` and `fontStyle` properties, there are multiple limitations to custom +fonts in React Native. Using custom [variable fonts](https://fonts.google.com/knowledge/introducing_type/introducing_variable_fonts) is especially problematic, with some platforms failing to render variants entirely. To ensure correct typography in your -app, we suggest installing each font variant as a separate file. Below you'll find example on how to set up React Native Paper -theme with custom fonts. +app, we suggest installing each font variant as a separate file. Below you'll find example on how to set up React Native Paper +theme with custom fonts. Should you decide to use a variable font anyway, second example will show you how to test if the font is rendered correctly in React Native on all platforms. - +
Variable fonts examples
    diff --git a/docs/docs/guides/08-theming-with-react-navigation.md b/docs/docs/guides/08-theming-with-react-navigation.md index 6003953c02..244b62cc03 100644 --- a/docs/docs/guides/08-theming-with-react-navigation.md +++ b/docs/docs/guides/08-theming-with-react-navigation.md @@ -11,25 +11,7 @@ But how to make them work together? ## Themes adaptation -### Material Design 2 - -Fortunately, in Material Design 2, both React Navigation and React Native Paper offer very similar API when it comes to theming and theme color structure. It's possible to import them in light and dark variants from both. - -```js -import { - DarkTheme as NavigationDarkTheme, - DefaultTheme as NavigationDefaultTheme, -} from '@react-navigation/native'; - -import { - MD2LightTheme, - MD2DarkTheme, -} from 'react-native-paper'; -``` - -### Material Design 3 - -From v5, React Native Paper theme colors structure follows the Material Design 3 (known as Material You) colors system, which differs significantly from both the previous Paper's theme and React Navigation theme. +From `v5`, React Native Paper theme colors structure follows the Material Design 3 (known as Material You) colors system, which differs significantly from both the previous Paper's theme and React Navigation theme. 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. @@ -49,10 +31,7 @@ const { LightTheme, DarkTheme } = adaptNavigationTheme({ Library exports also Material Design 3 themes in both modes: ```js -import { - MD3LightTheme, - MD3DarkTheme, -} from 'react-native-paper'; +import { LightTheme, DarkTheme } from 'react-native-paper'; ``` ## Combining theme objects @@ -117,8 +96,6 @@ export default function App() { } ``` - - Our goal here is to combine those two themes, so that we could control the theme for the entire application from a single place. To make things easier we can use [deepmerge](https://www.npmjs.com/package/deepmerge) package. We can install it with: @@ -127,26 +104,6 @@ To make things easier we can use [deepmerge](https://www.npmjs.com/package/deepm npm install deepmerge ``` -### Material Design 2 - -```js -import { - NavigationContainer, - DarkTheme as NavigationDarkTheme, - DefaultTheme as NavigationDefaultTheme, -} from '@react-navigation/native'; -import { - MD2DarkTheme, - MD2LightTheme, -} from 'react-native-paper'; -import merge from 'deepmerge'; - -const CombinedDefaultTheme = merge(MD2LightTheme, NavigationDefaultTheme); -const CombinedDarkTheme = merge(MD2DarkTheme, NavigationDarkTheme); -``` - -### Material Design 3 - ```js import { NavigationContainer, @@ -154,8 +111,8 @@ import { DefaultTheme as NavigationDefaultTheme, } from '@react-navigation/native'; import { - MD3DarkTheme, - MD3LightTheme, + DarkTheme as PaperDarkTheme, + LightTheme as PaperLightTheme, adaptNavigationTheme, } from 'react-native-paper'; import merge from 'deepmerge'; @@ -165,35 +122,12 @@ const { LightTheme, DarkTheme } = adaptNavigationTheme({ reactNavigationDark: NavigationDarkTheme, }); -const CombinedDefaultTheme = merge(MD3LightTheme, LightTheme); -const CombinedDarkTheme = merge(MD3DarkTheme, DarkTheme); +const CombinedDefaultTheme = merge(PaperLightTheme, LightTheme); +const CombinedDarkTheme = merge(PaperDarkTheme, DarkTheme); ``` Alternatively, we could merge those themes using vanilla JavaScript: -### Material Design 2 - -```js -const CombinedDefaultTheme = { - ...MD2LightTheme, - ...NavigationDefaultTheme, - colors: { - ...MD2LightTheme.colors, - ...NavigationDefaultTheme.colors, - }, -}; -const CombinedDarkTheme = { - ...MD2DarkTheme, - ...NavigationDarkTheme, - colors: { - ...MD2DarkTheme.colors, - ...NavigationDarkTheme.colors, - }, -}; -``` - -### Material Design 3 - ```js const { LightTheme, DarkTheme } = adaptNavigationTheme({ reactNavigationLight: NavigationDefaultTheme, @@ -201,18 +135,18 @@ const { LightTheme, DarkTheme } = adaptNavigationTheme({ }); const CombinedDefaultTheme = { - ...MD3LightTheme, + ...PaperLightTheme, ...LightTheme, colors: { - ...MD3LightTheme.colors, + ...PaperLightTheme.colors, ...LightTheme.colors, }, }; const CombinedDarkTheme = { - ...MD3DarkTheme, + ...PaperDarkTheme, ...DarkTheme, colors: { - ...MD3DarkTheme.colors, + ...PaperDarkTheme.colors, ...DarkTheme.colors, }, }; @@ -326,16 +260,12 @@ const Header = ({ scene }) => { - + ); }; @@ -350,7 +280,6 @@ Thanks to the linking of themes that we did earlier, switching themes can be con React Native Paper components will automatically use the provided theme thanks to the `PaperProvider` that is wrapped around the entry point of our application, but we can also access theme values manually with `useTheme` hook, exposed by the library. You can see how it's done in the `Header` component code above. -If light/dark themes are not enough for your use case, you can learn more about creating Material Design themes [here](https://material.io/design/material-theming/implementing-your-theme.html#color). -On `main` branch of the example app, you will find implemented [Menu](https://callstack.github.io/react-native-paper/docs/components/Menu) component, which allows you to choose a few custom themes. Inspecting code in `utils` and `Header` may give you some idea of how to use your own themes with `Paper`, in addition to dedicated [docs](https://callstack.github.io/react-native-paper/docs/components/Menu). +If light/dark themes are not enough for your use case, you can learn more about extending the Material Design theme [here](https://callstack.github.io/react-native-paper/docs/guides/theming#extending-the-theme). Read more about integrating `Paper` with `React Navigation` in a brilliant [article](https://reactnavigation.org/blog/2020/01/29/using-react-navigation-5-with-react-native-paper/) by [@trensik](https://twitter.com/trensik) diff --git a/docs/docs/guides/09-react-navigation.md b/docs/docs/guides/09-react-navigation.md index d9227cfb2b..04a3a9ae1e 100644 --- a/docs/docs/guides/09-react-navigation.md +++ b/docs/docs/guides/09-react-navigation.md @@ -6,14 +6,14 @@ title: Integrate AppBar with React Navigation ## Prerequisites - - `react-native-paper` - - `react-navigation` - +- `react-native-paper` +- `react-navigation` + We assume that you have already installed the mentioned libraries above, otherwise please check out the guides below. - - [React Native Paper - Getting Started](https://callstack.github.io/react-native-paper/docs/guides/getting-started) - - [React Navigation - Getting Started](https://reactnavigation.org/docs/getting-started/) + +[React Native Paper - Getting Started](https://callstack.github.io/react-native-paper/docs/guides/getting-started) + +[React Navigation - Getting Started](https://reactnavigation.org/docs/getting-started/) ## Stack Navigator @@ -46,7 +46,7 @@ At the moment our navigation stack contains two screens and will render `HomeScr ```js import React from 'react'; -import {View, Text, Button, StyleSheet} from 'react-native'; +import { View, Text, Button, StyleSheet } from 'react-native'; function HomeScreen() { return ( @@ -120,7 +120,8 @@ export default function App() { initialRouteName="Home" screenOptions={{ header: (props) => , - }}> + }} + > @@ -169,7 +170,12 @@ In order to achieve it, we firstly check, if the navigation bar receives a `back import { Appbar } from 'react-native-paper'; import { getHeaderTitle } from '@react-navigation/elements'; -export default function CustomNavigationBar({ navigation, route, options, back }) { +export default function CustomNavigationBar({ + navigation, + route, + options, + back, +}) { const title = getHeaderTitle(options, route.name); return ( @@ -186,6 +192,7 @@ export default function CustomNavigationBar({ navigation, route, options, back } ### Adding more items to `Appbar` Another interesting pattern that can be implemented with `react-native-paper` and `react-navigation` is a "menu" button. Thanks to the `Menu` component we can add a nice looking pop-up to our `Appbar`. To implement this feature we need to make a couple of changes in `CustomNavigationBar`: + - Render a `Menu` component - Pass `Appbar.Action` to the anchor prop - Add a state to control `Menu` visibility @@ -204,13 +211,15 @@ import { PaperProvider } from 'react-native-paper'; initialRouteName="Home" screenOptions={{ header: (props) => , - }}> + }} + > - +; ``` + ::: We also want the menu to appear only on `HomeScreen`, which means we will render it conditionally based on the `back` prop. @@ -240,12 +249,8 @@ export default function CustomNavigationBar({ - }> + anchor={} + > { console.log('Option 1 was pressed'); @@ -276,6 +281,6 @@ Final result: -That's all we need! We have app bar that contains everything we need to navigate through screens and access an additional menu on the main screen. As you can see, with Material design `Appbar` provided by `react-native-paper` used together with `react-navigation` we can easily create an app that looks and works great. +That's all we need! We have app bar that contains everything we need to navigate through screens and access an additional menu on the main screen. As you can see, with Material design `Appbar` provided by `react-native-paper` used together with `react-navigation` we can easily create an app that looks and works great. Grab the Expo [snack](https://snack.expo.dev/@react-native-paper/integrate-appbar-with-react-navigation) if you want to check the whole code! diff --git a/docs/docs/guides/10-migration-guide-to-5.0.md b/docs/docs/guides/10-migration-guide-to-5.0.md index 6c358d387f..5d1709842a 100644 --- a/docs/docs/guides/10-migration-guide-to-5.0.md +++ b/docs/docs/guides/10-migration-guide-to-5.0.md @@ -1,26 +1,26 @@ --- -title: Introducing v5 with Material You +title: Introducing Material You (v5) --- React Native Paper v5 is all about adopting the new Material Design 3 aka Material You. It was released in October 2021 after intense work and effort to make Material You follow a more expressive approach to design. -Paper now supports both Material Design 2 and 3 through the configuration described in [Versioning](#versioning) and is compatible with a handful of API changes. +Paper now supports both Material Design 2 and 3 through the configuration described in [Versioning](#versioning) and is compatible with a handful of API changes. # Migration guide to Material You 5.0 -Version 5.0 brings support for the next Material Design iteration branded as Material You (in fact being Material Design v3 or in short MD3) into the `react-native-paper` library. All the components were refined according to the official [design kit on figma](https://www.figma.com/community/file/1035203688168086460) and adjusted in terms of visuals by changes in colors, typography and animations. +Version 5.0 brings support for the next Material Design iteration branded as Material You (in fact being Material Design v3 or in short MD3) into the `react-native-paper` library. All the components were refined according to the official [design kit on figma](https://www.figma.com/community/file/1035203688168086460) and adjusted in terms of visuals by changes in colors, typography and animations. -Below you can find the most important information about the components whose API may have changed API has been changed due to supporting new props, renaming existing ones or some deprecations. Hopefully, based on the presented required changes, migration to the latest version should be smooth. Enjoy! +Below you can find the most important information about the components whose API may have changed API has been changed due to supporting new props, renaming existing ones or some deprecations. Hopefully, based on the presented required changes, migration to the latest version should be smooth. Enjoy! ### Installation -* The `v5` has been oficially released as a stable version, which means it will be installed by default from the `npm`. In order to do that, open a Terminal in your project's folder and run: +- The `v5` has been oficially released as a stable version, which means it will be installed by default from the `npm`. In order to do that, open a Terminal in your project's folder and run: ```bash npm2yarn 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. +- 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. ```bash npm2yarn npm install react-native-safe-area-context @@ -38,13 +38,13 @@ npx pod-install Introducing Material You (MD3) into `react-native-paper` doesn't mean dropping previous Material Design (MD2)! On the contrary, both of them will be supported, however, not simultaneously. To specify which design system components should follow in the app, there is a newly created property in [the theme](https://callstack.github.io/react-native-paper/docs/guides/theming#theme-properties) named `version` that accepts one of two values: -* 3 – (default) new Material You (MD3), -* 2 - previous Material Design (MD2). +- 3 – (default) new Material You (MD3), +- 2 - previous Material Design (MD2). ```js theme: { /* ... */ - version: 3 | 2 + version: 3 | 2; } ``` @@ -114,7 +114,7 @@ theme: { ## Typography -A new way of approaching typography introduces one component `` which accepts prop `variant`. Variant defines appropriate text styles for type role and its size. The updated type scale organizes styles into five roles that are named to describe their purposes: Display, Headline, Title, Label and Body along with three display styles large, medium, and small. In total, there are fifteen variants that are MD3 compliant and are reflecting design typography tokens written in camel case. +A new way of approaching typography introduces one component `` which accepts prop `variant`. Variant defines appropriate text styles for type role and its size. The updated type scale organizes styles into five roles that are named to describe their purposes: Display, Headline, Title, Label and Body along with three display styles large, medium, and small. In total, there are fifteen variants that are MD3 compliant and are reflecting design typography tokens written in camel case. :::info If any component uses Paper's `Text` component, without specified variant, then `default` variant is applied. @@ -140,11 +140,11 @@ If any component uses Paper's `Text` component, without specified variant Label Large Label Medium Label Small - ``` +``` Take a look at the suggested replacement diff: - ```diff +```diff - Headline + Headline @@ -159,8 +159,7 @@ Take a look at the suggested replacement diff: - Caption + Caption - ``` - +``` 👉 You can find more about typography on the [Material You website](https://m3.material.io/styles/typography/overview) @@ -169,23 +168,24 @@ Take a look at the suggested replacement diff: The existing utility called `configureFonts` was adjusted to help users configure their theme fonts in both version, that's why that function, as of today, is going to accept the object with the follwing properties as an argument: ```ts -configureFonts(params) +configureFonts(params); ``` Parameters: -| NAME | TYPE | REQUIRED | -| ----------- | ----------- | ----------- | -| params | object | No | +| NAME | TYPE | REQUIRED | +| ------ | ------ | -------- | +| params | object | No | Valid `params` keys are: - * `config` ([MD2FontsConfig](https://github.com/callstack/react-native-paper/blob/main/src/styles/fonts.tsx#L63) | [MD3FontsConfig](https://github.com/callstack/react-native-paper/blob/main/src/styles/fonts.tsx#L67)) - fonts config object appropriate to the MD version - * `isV3` (boolean) - whether adjusting theme fonts for v3. Default it true. +- `config` ([MD2FontsConfig](https://github.com/callstack/react-native-paper/blob/main/src/styles/fonts.tsx#L63) | [MD3FontsConfig](https://github.com/callstack/react-native-paper/blob/main/src/styles/fonts.tsx#L67)) - fonts config object appropriate to the MD version +- `isV3` (boolean) - whether adjusting theme fonts for v3. Default it true. To use your current font config from v2 and migrate to v3 there are two requirements: -* the font config previously passed directly into function has to be passed into the params object property called `config` -* the params object property `isV3` has to be set to `false` + +- the font config previously passed directly into function has to be passed into the params object property called `config` +- the params object property `isV3` has to be set to `false` ```diff - configureFonts(fontConfig) @@ -202,31 +202,25 @@ If you want to check how to use `configureFonts` on MD3, check the [Fonts](https `Appbar` and `Appbar.Header` in the latest version can be used in four various modes due to new prop `mode`: -* `small` - Appbar with default height (64) (default), -* `medium` - Appbar with medium height (112), -* `large` - Appbar with large height (152), -* `center-aligned` - Appbar with default height (64) and center-aligned title. +- `small` - Appbar with default height (64) (default), +- `medium` - Appbar with medium height (112), +- `large` - Appbar with large height (152), +- `center-aligned` - Appbar with default height (64) and center-aligned title. ```js - - /* ... */ - +/* ... */ ``` To make it easier for users to build the `BottomBar`, formed on the `Appbar` components, we have added a property `safeAreaInsets`: ```js - - /* ... */ - +/* ... */ ``` - + It's worth noting that by default the theme version 3 `Appbar` and `Appbar.Header` don't have a shadow. However, it can be added by passing prop `elevated` into the component: ```js - - /* ... */ - +/* ... */ ``` #### Appbar.Action @@ -259,9 +253,9 @@ According to the updates in `Surface` on the top of which `Banner`, `Searchbar` For the sake of new animation of pill shape, indicating active destination, and assisting icon change from outlined to filled, there are three changes within `navigationState.routes` property items: -* `color` is deprecated since color is constant and the same for all routes, -* `icon` is renamed to `focusedIcon`, as the name implies, with theme version 3 it's the outline icon used as focused tab icon and with theme version 2 it's a default icon, -* `unfocusedIcon` (optional) is the filled icon used as the unfocused tab icon, compatible with theme version 3. +- `color` is deprecated since color is constant and the same for all routes, +- `icon` is renamed to `focusedIcon`, as the name implies, with theme version 3 it's the outline icon used as focused tab icon and with theme version 2 it's a default icon, +- `unfocusedIcon` (optional) is the filled icon used as the unfocused tab icon, compatible with theme version 3. :::info `unfocusedIcon` is optional, if you can't find outline icon equivalent, omit that prop, so `focusedIcon` will be displayed in both active and inactive state. @@ -280,19 +274,21 @@ routes: [ ] ``` -The `compact` prop was also introduced, working with both themes. It indicates whether tabs should be spread across the entire width, especially in a horizontal mode. +The `compact` prop was also introduced, working with both themes. It indicates whether tabs should be spread across the entire width, especially in a horizontal mode. ```js ``` It's worth to mention that default value of prop `shifting` depends on the theme version: -* 3 - it's `false`, -* 2 - it's `true` when there are more than 3 tabs. + +- 3 - it's `false`, +- 2 - it's `true` when there are more than 3 tabs. Two additional props that control the scene animation were introduced that control the animation of the tabs when `sceneAnimationEnabled` is `true`: -* `sceneAnimationType: "opacity" | "shifting" | undefined` - defines the animation type for the scene. `shifting` enables a new animation where navigating to a scene will shift it horizontally into view. Both `opacity` and `undefined` have the same effect, fading the scene into view. -* `sceneAnimationEasing` allows specifying a custom easing function for the scene animation. + +- `sceneAnimationType: "opacity" | "shifting" | undefined` - defines the animation type for the scene. `shifting` enables a new animation where navigating to a scene will shift it horizontally into view. Both `opacity` and `undefined` have the same effect, fading the scene into view. +- `sceneAnimationEasing` allows specifying a custom easing function for the scene animation. ![shiftingAnimation](../../static/screenshots/bottom-navigation-shifting.gif) @@ -301,8 +297,9 @@ On a final note, please be aware that `BottomNavigation` with theme version 3 do ### Button `Button`'s property `mode` has been expanded with two additional options: -* `elevated` - button with a background color and elevation, used when absolutely necessary e.g. button requires visual separation from a patterned background, -* `container-tonal` - button with a secondary background color, an alternative middle ground between contained and outlined buttons. + +- `elevated` - button with a background color and elevation, used when absolutely necessary e.g. button requires visual separation from a patterned background, +- `container-tonal` - button with a secondary background color, an alternative middle ground between contained and outlined buttons. ```js <> @@ -316,8 +313,9 @@ On a final note, please be aware that `BottomNavigation` with theme version 3 do ``` The property `color` is deprecated, but in its place two new props called `buttonColor` and `textColor` are introduced: -* `buttonColor` - custom button's background color, -* `textColor` - custom button's text color. + +- `buttonColor` - custom button's background color, +- `textColor` - custom button's text color. ```diff - @@ -343,23 +341,21 @@ The `Card` component's property `mode` has been expanded with one additional opt Since there is no one right way to make a card, there is also no one right way for specifying a title and subtitle variant. Therefore two new props come in handy: -* `titleVariant` - title text variant defines appropriate text styles for type role and its size. -* `subtitleVariant` - subtitle text variant defines appropriate text styles for type role and its size. +- `titleVariant` - title text variant defines appropriate text styles for type role and its size. +- `subtitleVariant` - subtitle text variant defines appropriate text styles for type role and its size. ```js - + ``` ### Checkbox + #### Checkbox.Item `Checkbox.Item` similarly to `RadioButton.Item` has been expanded with the prop called `labelVariant`, which defines appropriate text styles for type role and its size. ```js - ``` @@ -368,18 +364,24 @@ Since there is no one right way to make a card, there is also no one right way f To properly compose `Chip` component and adjust into required type, there are three new props that will come in handy: -* `compact` - sets smaller horizontal paddings around the label, useful for `Chip` containing only the label, -* `elevated` - indicating whether `Chip` should be elevated, -* `showSelectedOverlay` - defining whether to display an overlay on a selected button. +- `compact` - sets smaller horizontal paddings around the label, useful for `Chip` containing only the label, +- `elevated` - indicating whether `Chip` should be elevated, +- `showSelectedOverlay` - defining whether to display an overlay on a selected button. ```js <> Compact Chip - Elevated Chip - Chip with selected overlay + + Elevated Chip + + + Chip with selected overlay + ``` + ### Dialog + #### Dialog.Icon `Dialog.Icon` is another freshly added component presenting an icon within a `Dialog`, placed at the top of the content. @@ -395,12 +397,13 @@ It's working only with theme version 3. ``` + ### Divider `Divider` component received two new props: -* `bold` - divider is bolded, -* `horizontalInset` - divider has horizontal insets on both sides. +- `bold` - divider is bolded, +- `horizontalInset` - divider has horizontal insets on both sides. Additionally prop `inset` was renamed to `leftInset`. @@ -410,6 +413,7 @@ Additionally prop `inset` was renamed to `leftInset`. ``` ### Drawer + #### Drawer.CollapsedItem (Navigation rail) `Drawer.CollapsedItem` is a newly created side navigation component that can be used within `Drawer`, representing a destination in the form of an action item with an icon and optionally label. @@ -456,15 +460,15 @@ With the latest version, there is a possibility to specify whether `Drawer.Secti `FAB`, `AnimatedFAB` and `FAB.Group` in the latest version can be used with four variants and two modes, thanks to two new props: -* `variant` defines color mappings variant for combinations of container and icon colors. Can be one of: primary (default), secondary, tertiary or surface. +- `variant` defines color mappings variant for combinations of container and icon colors. Can be one of: primary (default), secondary, tertiary or surface. ```js ``` -* `mode` specifies whether a button should be flat or elevated: - - `flat` - button without a shadow, - - `elevated` - button with a shadow. +- `mode` specifies whether a button should be flat or elevated: + - `flat` - button without a shadow, + - `elevated` - button with a shadow. ```js @@ -472,11 +476,11 @@ With the latest version, there is a possibility to specify whether `Drawer.Secti #### FAB -Additionaly `FAB` may be applied in one of three available sizes, thanks to new prop `size`: +Additionaly `FAB` may be applied in one of three available sizes, thanks to new prop `size`: -* `small` - FAB with small height (40), -* `medium` - Appbar with default medium height (56), -* `large` - Appbar with large height (96). +- `small` - FAB with small height (40), +- `medium` - Appbar with default medium height (56), +- `large` - Appbar with large height (96). ```js @@ -504,7 +508,7 @@ There is also deprecation in one of the `actions` properties, namely `small` pro + ``` -Additionally, the action item property previously known as `labelStyle` was renamed to `containerStyle` since it's tied mostly with the container styles. At the same time, `labelStyle` is still available with the new role related to styling item label. +Additionally, the action item property previously known as `labelStyle` was renamed to `containerStyle` since it's tied mostly with the container styles. At the same time, `labelStyle` is still available with the new role related to styling item label. ```diff - @@ -515,13 +519,13 @@ Additionally, the action item property previously known as `labelStyle` was rena `IconButton` received two new props: -* `selected` sets alternative combination of icon and container color, +- `selected` sets alternative combination of icon and container color, ```js ``` -* `containerColor` custom background color of the icon container. +- `containerColor` custom background color of the icon container. ```js @@ -535,12 +539,13 @@ At the same time, the `color` prop was renamed to `iconColor`. ``` ### Menu + #### Menu.Item `Menu.Item` received two new props: -* `dense` sets smaller item height for more condensed layout, -* `trailingIcon` which handles displaying an icon at the end of the item row. +- `dense` sets smaller item height for more condensed layout, +- `trailingIcon` which handles displaying an icon at the end of the item row. ```js @@ -554,19 +559,20 @@ At the same time, by analogy to the second new prop, the `icon` prop was renamed ``` ### RadioButton + ##### RadioButton.Item `RadioButton.Item` has been expanded with the prop called `labelVariant`, which defines appropriate text styles for type role and its size. ```js - ``` ### SegmentedButtons -`SegmentedButtons` is a completely new component introduced in the latest version. It allows people to select options, switch views, or sort elements. It supports single and multiselect select variant and provide a lot +`SegmentedButtons` is a completely new component introduced in the latest version. It allows people to select options, switch views, or sort elements. It supports single and multiselect select variant and provide a lot of customization options. ![segmentedButtons](../../static/screenshots/segmentedbuttons.gif) @@ -576,24 +582,24 @@ const MyComponent = () => { const [value, setValue] = React.useState(''); return ( - + ); }; ``` @@ -602,14 +608,15 @@ const MyComponent = () => { `Snackbar` due to the optional close affordance, in form of `IconButton` (located on the right side of action button), received three new props: -* `icon` - icon to display when `onIconPress` is defined. Default will be `close` icon. -* `onIconPress` - function to execute on icon button press. The icon button appears only when this prop is specified. -* `iconAccessibilityLabel` - accessibility label for the icon button. +- `icon` - icon to display when `onIconPress` is defined. Default will be `close` icon. +- `onIconPress` - function to execute on icon button press. The icon button appears only when this prop is specified. +- `iconAccessibilityLabel` - accessibility label for the icon button. ### Surface `Surface` component received one new prop: -* `elevation` - accepts values from `0` to `5` and applies background color and shadows to the `Surface` component. Supports both iOS and Android. + +- `elevation` - accepts values from `0` to `5` and applies background color and shadows to the `Surface` component. Supports both iOS and Android. Previously `elevation` was passed inside the `style` prop. Since it supported not only Android, but also iOS, we decided to extract it from `style` and create a separate `elevation` prop for that. @@ -619,9 +626,10 @@ Previously `elevation` was passed inside the `style` prop. Since it supported no ``` ### TextInput + #### TextInput.Icon -The property `name` was renamed to `icon`, since the scope and type of that prop is much wider than just the icon name – it accepts also the function which receives an object with color and size properties and +The property `name` was renamed to `icon`, since the scope and type of that prop is much wider than just the icon name – it accepts also the function which receives an object with color and size properties and ```diff - @@ -634,7 +642,6 @@ Component displayed upon tapping and holding a screen element or component used ![tooltip](../../static/screenshots/tooltips.gif) - ```js {}} /> @@ -645,8 +652,9 @@ Component displayed upon tapping and holding a screen element or component used With this, that’s a wrap. -The update wouldn't happen without a group of great React Native experts I'm happy to work with. +The update wouldn't happen without a group of great React Native experts I'm happy to work with. From this place I would like to thank: + - [Daniel Szczepanik](https://github.com/Drakeoon) for his commitment, effort and collaborative work on adjusting components, - [Olimpia Zurek](https://github.com/OlimpiaZurek) for her contribution and help, - [Aleksandra Desmurs-Linczewska](https://github.com/p-syche), [Jan Jaworski](https://github.com/jaworek) and [Kewin Wereszczyński](https://github.com/kwereszczynski) for checking and testing changes as well as providing valuable feedback, diff --git a/docs/docs/guides/11-ripple-effect.md b/docs/docs/guides/11-ripple-effect.md index 1e14a73082..a5d3501fd2 100644 --- a/docs/docs/guides/11-ripple-effect.md +++ b/docs/docs/guides/11-ripple-effect.md @@ -40,6 +40,3 @@ import { Provider as PaperProvider } from 'react-native-paper'; // ... ``` - - -