feat: add possibility to override touchable ripple color (#3866)

Author: lukewalczak

docs/docs/guides/11-ripple-effect.md

@@ -0,0 +1,45 @@
+---
+title: Ripple effect
+---
+
+The ripple effect is a visual feedback that occurs when a user interacts with a pressable UI element, such as a button. This response takes the form of a circular ripple expanding from the point of contact, much like a drop falling into water and creating ripples.
+
+The ripple effect is an essential aspect of Material Design, and Paper's pressable components have it enabled by default. Nonetheless, it can be tailored to suit specific needs.
+
+:::note
+The ripple effect on the iOS platform is replaced by a highlight effect.
+:::
+
+## Customize ripple effect color in component
+
+The `rippleColor` prop is available for every pressable component which allows you to set the color of the ripple effect. For the instance, to make the `Button` component's ripple effect transparent, simply pass the desired color value to the prop:
+
+```
+<Button
+  rippleColor="#FF000020"
+  icon="camera"
+  mode="contained"
+  onPress={() => console.log('Pressed')}>
+  Press me
+</Button>
+```
+
+## Disable ripple effect in all components
+
+To disable the ripple effect in **all** of Paper's components set `rippleEffectEnabled: false` on the `settings` prop of `PaperProvider`.
+
+```
+import { Provider as PaperProvider } from 'react-native-paper';
+// ...
+
+<PaperProvider
+  settings={{
+    rippleEffectEnabled: false
+  }}
+>
+  // ...
+</PaperProvider>
+```
+
+
+

example/src/DrawerItems.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { I18nManager, StyleSheet, View } from 'react-native';
+import { I18nManager, StyleSheet, View, Platform } from 'react-native';
 
 import { DrawerContentScrollView } from '@react-navigation/drawer';
 import * as Updates from 'expo-updates';
@@ -23,7 +23,9 @@ type Props = {
   toggleThemeVersion: () => void;
   toggleCollapsed: () => void;
   toggleCustomFont: () => void;
+  toggleRippleEffect: () => void;
   customFontLoaded: boolean;
+  rippleEffectEnabled: boolean;
   collapsed: boolean;
   isRTL: boolean;
   isDarkTheme: boolean;
@@ -103,7 +105,9 @@ const DrawerItems = ({
   toggleThemeVersion,
   toggleCollapsed,
   toggleCustomFont,
+  toggleRippleEffect,
   customFontLoaded,
+  rippleEffectEnabled,
   collapsed,
   isRTL,
   isDarkTheme,
@@ -115,6 +119,8 @@ const DrawerItems = ({
 
   const { isV3, colors } = useExampleTheme();
 
+  const isIOS = Platform.OS === 'ios';
+
   const _handleToggleRTL = () => {
     toggleRTL();
     I18nManager.forceRTL(!isRTL);
@@ -222,6 +228,17 @@ const DrawerItems = ({
                 </View>
               </TouchableRipple>
             )}
+
+            <TouchableRipple onPress={toggleRippleEffect}>
+              <View style={[styles.preference, isV3 && styles.v3Preference]}>
+                <Text variant="labelLarge">
+                  {isIOS ? 'Highlight' : 'Ripple'} effect *
+                </Text>
+                <View pointerEvents="none">
+                  <Switch value={rippleEffectEnabled} />
+                </View>
+              </View>
+            </TouchableRipple>
           </Drawer.Section>
           {isV3 && !collapsed && (
             <Text variant="bodySmall" style={styles.annotation}>

example/src/Examples/ChipExample.tsx

@@ -10,7 +10,7 @@ import ScreenWrapper from '../ScreenWrapper';
 const ChipExample = () => {
   const [visible, setVisible] = React.useState<boolean>(false);
   const { isV3 } = useExampleTheme();
-  const customColor = isV3 ? MD3Colors.secondary20 : MD2Colors.purple900;
+  const customColor = isV3 ? MD3Colors.error50 : MD2Colors.purple900;
 
   return (
     <>

example/src/index.tsx

@@ -48,6 +48,8 @@ const DrawerContent = () => {
           toggleThemeVersion={preferences.toggleThemeVersion}
           toggleCollapsed={preferences.toggleCollapsed}
           toggleCustomFont={preferences.toggleCustomFont}
+          toggleRippleEffect={preferences.toggleRippleEffect}
+          rippleEffectEnabled={preferences.rippleEffectEnabled}
           customFontLoaded={preferences.customFontLoaded}
           collapsed={preferences.collapsed}
           isRTL={preferences.rtl}
@@ -79,6 +81,7 @@ export default function PaperExample() {
   );
   const [collapsed, setCollapsed] = React.useState(false);
   const [customFontLoaded, setCustomFont] = React.useState(false);
+  const [rippleEffectEnabled, setRippleEffectEnabled] = React.useState(true);
 
   const themeMode = isDarkMode ? 'dark' : 'light';
 
@@ -164,17 +167,20 @@ export default function PaperExample() {
       toggleRtl: () => setRtl((rtl) => !rtl),
       toggleCollapsed: () => setCollapsed(!collapsed),
       toggleCustomFont: () => setCustomFont(!customFontLoaded),
+      toggleRippleEffect: () => setRippleEffectEnabled(!rippleEffectEnabled),
       toggleThemeVersion: () => {
         setCustomFont(false);
         setCollapsed(false);
         setThemeVersion((oldThemeVersion) => (oldThemeVersion === 2 ? 3 : 2));
+        setRippleEffectEnabled(true);
       },
+      rippleEffectEnabled,
       customFontLoaded,
       collapsed,
       rtl,
       theme,
     }),
-    [rtl, theme, collapsed, customFontLoaded]
+    [rtl, theme, collapsed, customFontLoaded, rippleEffectEnabled]
   );
 
   if (!isReady && !fontsLoaded) {
@@ -215,7 +221,10 @@ export default function PaperExample() {
   };
 
   return (
-    <PaperProvider theme={customFontLoaded ? configuredFontTheme : theme}>
+    <PaperProvider
+      settings={{ rippleEffectEnabled: preferences.rippleEffectEnabled }}
+      theme={customFontLoaded ? configuredFontTheme : theme}
+    >
       <PreferencesContext.Provider value={preferences}>
         <React.Fragment>
           <NavigationContainer

src/components/BottomNavigation/BottomNavigation.tsx

@@ -1,6 +1,7 @@
 import * as React from 'react';
 import {
   Animated,
+  ColorValue,
   EasingFunction,
   Platform,
   StyleProp,
@@ -47,7 +48,7 @@ type TouchableProps<Route extends BaseRoute> = TouchableWithoutFeedbackProps & {
   children: React.ReactNode;
   borderless?: boolean;
   centered?: boolean;
-  rippleColor?: string;
+  rippleColor?: ColorValue;
 };
 
 export type Props<Route extends BaseRoute> = {

src/components/BottomNavigation/BottomNavigationBar.tsx

@@ -62,7 +62,7 @@ type TouchableProps<Route extends BaseRoute> = TouchableWithoutFeedbackProps & {
   children: React.ReactNode;
   borderless?: boolean;
   centered?: boolean;
-  rippleColor?: string;
+  rippleColor?: ColorValue;
 };
 
 export type Props<Route extends BaseRoute> = {

src/components/Button/Button.tsx

@@ -1,6 +1,7 @@
 import * as React from 'react';
 import {
   Animated,
+  ColorValue,
   GestureResponderEvent,
   StyleProp,
   StyleSheet,
@@ -54,6 +55,10 @@ export type Props = $Omit<React.ComponentProps<typeof Surface>, 'mode'> & {
    * Custom button's text color.
    */
   textColor?: string;
+  /**
+   * Color of the ripple effect.
+   */
+  rippleColor?: ColorValue;
   /**
    * Whether to show a loading indicator.
    */
@@ -171,6 +176,7 @@ const Button = ({
   icon,
   buttonColor: customButtonColor,
   textColor: customTextColor,
+  rippleColor: customRippleColor,
   children,
   accessibilityLabel,
   accessibilityHint,
@@ -255,7 +261,8 @@ const Button = ({
       dark,
     });
 
-  const rippleColor = color(textColor).alpha(0.12).rgb().string();
+  const rippleColor =
+    customRippleColor || color(textColor).alpha(0.12).rgb().string();
 
   const buttonStyle = {
     backgroundColor,

src/components/Chip/Chip.tsx

@@ -2,6 +2,7 @@ import * as React from 'react';
 import {
   AccessibilityState,
   Animated,
+  ColorValue,
   GestureResponderEvent,
   Platform,
   StyleProp,
@@ -62,6 +63,10 @@ export type Props = $Omit<React.ComponentProps<typeof Surface>, 'mode'> & {
    * Whether to display overlay on selected chip
    */
   showSelectedOverlay?: boolean;
+  /**
+   * Color of the ripple effect.
+   */
+  rippleColor?: ColorValue;
   /**
    * Whether the chip is disabled. A disabled chip is greyed out and `onPress` is not called on touch.
    */
@@ -105,7 +110,6 @@ export type Props = $Omit<React.ComponentProps<typeof Surface>, 'mode'> & {
    */
   textStyle?: StyleProp<TextStyle>;
   style?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
-
   /**
    * @optional
    */
@@ -165,6 +169,7 @@ const Chip = ({
   theme: themeOverrides,
   testID = 'chip',
   selectedColor,
+  rippleColor: customRippleColor,
   showSelectedOverlay = false,
   ellipsizeMode,
   compact,
@@ -213,7 +218,7 @@ const Chip = ({
     borderColor,
     textColor,
     iconColor,
-    underlayColor,
+    rippleColor,
     selectedBackgroundColor,
     backgroundColor,
   } = getChipColors({
@@ -223,6 +228,7 @@ const Chip = ({
     showSelectedOverlay,
     customBackgroundColor,
     disabled,
+    customRippleColor,
   });
 
   const accessibilityState: AccessibilityState = {
@@ -272,7 +278,7 @@ const Chip = ({
         onPressOut={hasPassedTouchHandler ? handlePressOut : undefined}
         onLongPress={onLongPress}
         delayLongPress={delayLongPress}
-        underlayColor={underlayColor}
+        rippleColor={rippleColor}
         disabled={disabled}
         accessibilityLabel={accessibilityLabel}
         accessibilityRole="button"

src/components/Chip/helpers.tsx

@@ -224,13 +224,22 @@ const getIconColor = ({
   return color(theme.colors.text).alpha(0.54).rgb().string();
 };
 
-const getUnderlayColor = ({
+const getRippleColor = ({
   theme,
   isOutlined,
   disabled,
   selectedColor,
   selectedBackgroundColor,
-}: BaseProps & { selectedBackgroundColor: string; selectedColor?: string }) => {
+  customRippleColor,
+}: BaseProps & {
+  selectedBackgroundColor: string;
+  selectedColor?: string;
+  customRippleColor?: ColorValue;
+}) => {
+  if (customRippleColor) {
+    return customRippleColor;
+  }
+
   const isSelectedColor = selectedColor !== undefined;
   const textColor = getTextColor({
     theme,
@@ -261,11 +270,13 @@ export const getChipColors = ({
   showSelectedOverlay,
   customBackgroundColor,
   disabled,
+  customRippleColor,
 }: BaseProps & {
   customBackgroundColor?: ColorValue;
   disabled?: boolean;
   showSelectedOverlay?: boolean;
   selectedColor?: string;
+  customRippleColor?: ColorValue;
 }) => {
   const baseChipColorProps = { theme, isOutlined, disabled };
 
@@ -294,10 +305,11 @@ export const getChipColors = ({
       ...baseChipColorProps,
       selectedColor,
     }),
-    underlayColor: getUnderlayColor({
+    rippleColor: getRippleColor({
       ...baseChipColorProps,
       selectedColor,
       selectedBackgroundColor,
+      customRippleColor,
     }),
     backgroundColor,
     selectedBackgroundColor,

src/components/DataTable/DataTableCell.tsx

@@ -60,6 +60,8 @@ export type Props = $RemoveChildren<typeof TouchableRipple> & {
  *
  * If you want to support multiline text, please use View instead, as multiline text doesn't comply with
  * MD Guidelines (https://github.com/callstack/react-native-paper/issues/2381).
+ *
+ * @extends TouchableRipple props https://callstack.github.io/react-native-paper/docs/components/TouchableRipple
  */
 
 const DataTableCell = ({