diff --git a/docs/docs/guides/02-theming.mdx b/docs/docs/guides/02-theming.mdx index beeb8bfaff..fe1e445a83 100644 --- a/docs/docs/guides/02-theming.mdx +++ b/docs/docs/guides/02-theming.mdx @@ -473,10 +473,6 @@ export default function HomeScreen() { 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)). -### Migrating from Material Design 2 - -If you are upgrading from Material Design 2 (4.x and lower), follow the [Migration Guide](https://callstack.github.io/react-native-paper/docs/guides/migration-guide-to-5.0). - ## Applying a theme to a paper component If you want to change the theme for a certain component from the library, you can directly pass the `theme` prop to the component. The theme passed as the prop is merged with the theme from the `PaperProvider`: diff --git a/docs/docs/guides/10-migration-guide-to-5.0.md b/docs/docs/guides/10-migration-guide-to-5.0.md deleted file mode 100644 index 178900d2e3..0000000000 --- a/docs/docs/guides/10-migration-guide-to-5.0.md +++ /dev/null @@ -1,629 +0,0 @@ ---- -title: Introducing v5 with Material You ---- - -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. - -Current releases use Material Design 3 only; the historical `version: 2` / MD2 theme APIs described below were removed after v5. Use this guide when upgrading older apps to MD3. - -# 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. - -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: - -```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. - -```bash npm2yarn -npm install react-native-safe-area-context -``` - -Additionaly for `iOS` platform there is a requirement to link the native parts of the library: - -```bash -npx pod-install -``` - -## Theming - -### Versioning - -In v5, Material You (MD3) became the default theme. Earlier releases also exposed `version: 2` for Material Design 2; that option and MD2 theme exports have since been removed—use MD3 themes (`MD3LightTheme` / `MD3DarkTheme`) only. - -The theme object no longer includes `version` or `isV3`. Material Design 3 is the only supported mode; use `MD3LightTheme` / `MD3DarkTheme` (or a custom object matching the `MD3Theme` shape) without setting a version flag. - -Read more about theming in the [theming guide](https://callstack.github.io/react-native-paper/docs/guides/theming). - -### Colors - -New theme introduces a new color palette along with new namings reflecting design color tokens, but written in camel case. Palette contains a set of five key colors, where primary, secondary and tertiary are classified into accent colors. The second group of colors is neutral and neutral variant colors used for defining surface or background roles as well as specifying high and medium emphasis text and icons. Additionally, the color system includes a semantic color role for error. - -Each accent and error colors has a group of related tones. The tones are mapped to roles that create contrast and visual interest when applied to elements in the UI. - -:::note -Dynamic colors are not supported yet -::: - -![color-palette](../../static/migration/color-palette.png) - -Colors theme structure should follow the default palette and contain the following properties: - -```js -theme: { - /* ... */ - colors: { - primary, - primaryContainer, - secondary, - secondaryContainer, - tertiary, - tertiaryContainer, - surface, - surfaceVariant, - surfaceDisabled, - background, - error, - errorContainer, - onPrimary, - onPrimaryContainer, - onSecondary, - onSecondaryContainer, - onTertiary, - onTertiaryContainer, - onSurface, - onSurfaceVariant, - onSurfaceDisabled, - onError, - onErrorContainer, - onBackground, - outline, - shadow, - inverseOnSurface, - inverseSurface, - inversePrimary, - backdrop, - elevation: { - level0, - level1, - level2, - level3, - level4, - level5 - } - } -} -``` - -👉 You can find more about color on the [Material You website](https://m3.material.io/styles/color/the-color-system/key-colors-tones) - -## 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. - -:::info -If any component uses Paper's `Text` component, without specified variant, then `default` variant is applied. -::: - -```js -Display Large -Display Medium -Display small - -Headline Large -Headline Medium -Headline Small - -Title Large -Title Medium -Title Small - -Body Large -Body Medium -Body Small - -Label Large -Label Medium -Label Small - ``` - -Take a look at the suggested replacement diff: - - ```diff -- Headline -+ Headline - -- Title -+ Title - -- Subheading -+ Subheading - -- Paragraph -+ Paragraph - -- Caption -+ Caption - ``` - -:::caution -The standalone components `Caption`, `Headline`, `Paragraph`, `Subheading`, and `Title` are no longer exported from `react-native-paper`. Use `` as in the diff above. -::: - -👉 You can find more about typography on the [Material You website](https://m3.material.io/styles/typography/overview) - -### Configure fonts - -The `configureFonts` helper configures the Material Design 3 typescale. Pass overrides via the `config` object (see [Fonts](https://callstack.github.io/react-native-paper/docs/guides/fonts.html)). - -```ts -configureFonts({ config: { bodyLarge: { fontFamily: 'System' } } }) -``` - -Older direct calls like `configureFonts(fontConfig)` and MD2 platform-split configs should be replaced with MD3 variant keys (`displayLarge`, `bodyMedium`, and so on). - -## Components - -### Appbar (Top app bar) - -`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. - -```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 - -`Appbar.Action` received new prop `isLeading`, which defines whether it's the leading button and should be placed at the beginning of the `Appbar`. - -```js - {}} /> -``` - -#### Appbar.Content - -New design guidelines indicate there is no subtitle in `Appbar.Content`, that's why there are two deprecations and the following props won't be supported anymore: `subtitle` and `subtitleStyle`. - -```diff -- -+ -``` - -### Banner, Searchbar and Snackbar - -According to the updates in `Surface` on the top of which `Banner`, `Searchbar` and `Snackbar` are implemented, all three component received `elevation` prop to adjust its value. - -```diff -- Hello -+ Hello -``` - -### BottomNavigation (Navigation bar) - -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. - -:::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. -::: - -```diff -routes: [ -- { key: "album", title: "Album", icon: "image-album", color: "#3F51B5" }, -+ { key: "album", title: "Album", focusedIcon: "image-album" }, -- { key: "library", title: "Library", icon: "inbox", color: "#009688" }, -+ { key: "library", title: "Library", focusedIcon: "inbox", unfocusedIcon: "inbox-outline" }, -- { key: "favorites", title: "Favorites", icon: "heart", color: "#795548" }, -+ { key: "favorites", title: "Favorites", focusedIcon: "heart", unfocusedIcon: "heart-outline; }, -- { key: "purchased", title: "Purchased", icon: "shopping-cart", color: "#607D8B" }, -+ { key: "purchased", title: "Purchased", focusedIcon: "shopping-cart" }, -] -``` - -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. - -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. - -![shiftingAnimation](../../static/screenshots/bottom-navigation-shifting.gif) - -On a final note, please be aware that `BottomNavigation` with theme version 3 doesn't have a shadow. - -### 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. - -```js -<> - - - -``` - -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. - -```diff -- -+ -``` - -```diff -- -+ -``` - -Please be aware that along with theme version 3, by default text in the `Button` component isn't uppercased and `contained` button doesn't have any shadow (use then `elevated`). - -### Card - -The `Card` component's property `mode` has been expanded with one additional option called `contained`, which applies to the card's specified background color without any elevation and border. - -```js - -``` - -#### Card.Title - -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. - -```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 - -``` - -### Chip - -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. - -```js -<> - Compact Chip - 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. - -:::caution -It's working only with theme version 3. -::: - -```js - - - - - -``` -### Divider - -`Divider` component received two new props: - -* `bold` - divider is bolded, -* `horizontalInset` - divider has horizontal insets on both sides. - -Additionally prop `inset` was renamed to `leftInset`. - -```diff -- -+ -``` - -### 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. - -:::caution -It's working only with theme version 3. -::: - -```js - - - - -``` - -#### Drawer.Section - -With the latest version, there is a possibility to specify whether `Drawer.Section` should have a separator, in form of `Divider` component, displayed at the end of the section. To adjust it, a new property called `showDivider` was introduced, which by default is `true`: - -```js - - - - -``` - -### FAB - -`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. - -```js - -``` - -* `mode` specifies whether a button should be flat or elevated: - - `flat` - button without a shadow, - - `elevated` - button with a shadow. - -```js - -``` - -#### FAB - -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). - -```js - -``` - -However, if you would like to have your own size of `FAB`, there is a new prop called `customSize`: - -```js - -``` - -Accordingly to introducing `size="small"`, prop `small` was deprecated. - -```diff -- -+ -``` - -#### FAB.Group - -There is also deprecation in one of the `actions` properties, namely `small` prop is deprecated and replaced in favour of the default `size="small"`. - -```diff -- -+ -``` - -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 -- -+ -``` - -### IconButton - -`IconButton` received two new props: - -* `selected` sets alternative combination of icon and container color, - -```js - -``` - -* `containerColor` custom background color of the icon container. - -```js - -``` - -At the same time, the `color` prop was renamed to `iconColor`. - -```diff -- -+ -``` - -### 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. - -```js - -``` - -At the same time, by analogy to the second new prop, the `icon` prop was renamed to `leadingIcon`. - -```diff -- {}} title="Redo" /> -+ {}} title="Redo" /> -``` - -### 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 -of customization options. - -![segmentedButtons](../../static/screenshots/segmentedbuttons.gif) - -```js -const MyComponent = () => { - const [value, setValue] = React.useState(''); - - return ( - - ); -}; -``` - -### Snackbar - -`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. - -### 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. - -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. - -```diff -- -+ -``` - -### 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 - -```diff -- -+ -``` - -## Tooltip - -Component displayed upon tapping and holding a screen element or component used to present an informative text label identifying an element, such as a description of its function. - -![tooltip](../../static/screenshots/tooltips.gif) - - -```js - - {}} /> - -``` - -## Credits - -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. -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, -- [Bruno Castro](https://github.com/brunohkbx) for creating a long-awaited `Tooltip` component, -- [Muhammad Hur Ali](https://github.com/hurali97) for various bug fixes and `List` subcomponents adjustments, - -and, last but not least, [Satya Sahoo](https://github.com/satya164) for his mentoring during the process. diff --git a/docs/static/llms.txt b/docs/static/llms.txt index 4029ace3ea..3244326f67 100644 --- a/docs/static/llms.txt +++ b/docs/static/llms.txt @@ -17,7 +17,6 @@ - Icons: https://callstack.github.io/react-native-paper/docs/guides/icons - Fonts: https://callstack.github.io/react-native-paper/docs/guides/fonts - React Native Web: https://callstack.github.io/react-native-paper/docs/guides/react-native-web -- Migration to v5: https://callstack.github.io/react-native-paper/docs/guides/migration-guide-to-5.0 - Recommended Libraries: https://callstack.github.io/react-native-paper/docs/guides/recommended-libraries - Contributing: https://callstack.github.io/react-native-paper/docs/guides/contributing - Bottom Navigation: https://callstack.github.io/react-native-paper/docs/guides/bottom-navigation diff --git a/example/src/Examples/IconButtonExample.tsx b/example/src/Examples/IconButtonExample.tsx index a2ac7e72db..2b90a4ebd4 100644 --- a/example/src/Examples/IconButtonExample.tsx +++ b/example/src/Examples/IconButtonExample.tsx @@ -137,7 +137,7 @@ const ButtonExample = () => { mode="contained" style={styles.slightlyRounded} size={24} - contentStyle={{ padding: 8 }} + contentStyle={styles.contentPadding} iconColor={MD3Colors.tertiary50} onPress={() => {}} /> @@ -190,6 +190,9 @@ const styles = StyleSheet.create({ width: 48, height: 48, }, + contentPadding: { + padding: 8, + }, differentBorderRadius: { borderTopLeftRadius: 2, borderTopRightRadius: 4, diff --git a/example/src/index.native.tsx b/example/src/index.native.tsx index c6bba2b1bd..880fc4f04c 100644 --- a/example/src/index.native.tsx +++ b/example/src/index.native.tsx @@ -13,9 +13,9 @@ import { PaperProvider, MD3DarkTheme, MD3LightTheme } from 'react-native-paper'; import { SafeAreaInsetsContext } from 'react-native-safe-area-context'; import DrawerItems from './DrawerItems'; +import { PreferencesContext } from './PreferencesContext'; import App from './RootNavigator'; import { deviceColorsSupported } from '../utils'; -import { PreferencesContext } from './PreferencesContext'; import { CombinedDefaultTheme, CombinedDarkTheme, diff --git a/src/components/BottomNavigation/BottomNavigation.tsx b/src/components/BottomNavigation/BottomNavigation.tsx index a15cdd0110..d0cd447295 100644 --- a/src/components/BottomNavigation/BottomNavigation.tsx +++ b/src/components/BottomNavigation/BottomNavigation.tsx @@ -418,13 +418,11 @@ const BottomNavigation = ({ }); }, [ - shifting, navigationState.routes, offsetsAnims, scale, tabsPositionAnims, sceneAnimationEasing, - theme, ] ); diff --git a/src/components/TouchableRipple/TouchableRipple.native.tsx b/src/components/TouchableRipple/TouchableRipple.native.tsx index 1cb17b4068..3f8c791c33 100644 --- a/src/components/TouchableRipple/TouchableRipple.native.tsx +++ b/src/components/TouchableRipple/TouchableRipple.native.tsx @@ -73,12 +73,13 @@ const TouchableRipple = ( underlayColor, }); - // A workaround for ripple on Android P is to use useForeground + overflow: 'hidden' + // Use foreground ripple on Android P+ to ensure visibility. + // Background ripple requires the view to have a background drawable, + // which isn't always present. Foreground ripple needs overflow: 'hidden' + // to stay within bounds. // https://github.com/facebook/react-native/issues/6480 const useForeground = - Platform.OS === 'android' && - Platform.Version >= ANDROID_VERSION_PIE && - borderless; + Platform.OS === 'android' && Platform.Version >= ANDROID_VERSION_PIE; if (TouchableRipple.supported) { const androidRipple = rippleEffectEnabled @@ -94,7 +95,7 @@ const TouchableRipple = ( {...rest} ref={ref} disabled={disabled} - style={[borderless && styles.overflowHidden, style]} + style={[useForeground && styles.overflowHidden, style]} android_ripple={androidRipple} > {React.Children.only(children)}