You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Gesture handler library provides native components that can act as buttons. These can be treated as a replacement to `TouchableHighlight` or `TouchableOpacity` from RN core. Gesture handler's buttons recognize touches in native which makes the recognition process deterministic, allows for rendering ripples on Android in highly performant way (`TouchableNativeFeedback`requires that touch event does a roundtrip to JS before we can update ripple effect, which makes ripples lag a bit on older phones), and provides native and platform default interaction for buttons that are placed in a scrollable container (in which case the interaction is slightly delayed to prevent button from highlighting when you fling).
14
+
The Gesture Handler library offers native components that function as buttons, serving as alternatives to `TouchableHighlight` or `TouchableOpacity` from the core React Native framework. These buttons process touch recognition natively, which ensures a deterministic response. This capability significantly enhances performance; for example, it allows for immediate ripple effects on Android, unlike `TouchableNativeFeedback`, which requires a touch event roundtrip to JavaScript that can cause delays, especially noticeable on older devices. Additionally, these components handle default platform interactions natively, particularly in scrollable containers where interactions are smartly delayed to prevent unintended highlighting during a fling.
15
15
16
-
Currently Gesture handler library exposes three components that render native touchable elements under the hood:
16
+
Currently Gesture Handler library exposes three components that render native touchable elements under the hood:
On top of that all the buttons are wrapped with `NativeViewGestureHandler` and therefore allow for all the [common gesture handler properties](/docs/gestures/use-native-gesture#properties-common-to-all-gestures)and `NativeViewGestureHandler`'s [extra properties](/docs/gestures/use-native-gesture#properties-specific-to-nativegesture) to be applied to them.
22
+
On top of that all the buttons are wrapped with [`Native`](/docs/gestures/use-native-gesture) gesture and therefore allow for all its [properties](/docs/gestures/use-native-gesture#config) to be applied to them.
23
23
24
-
**IMPORTANT**: In order to make buttons accessible, you have to wrap your children in a `View` with `accessible` and `accessibilityRole="button"` props.
25
-
Example:
24
+
## BaseButton
26
25
27
-
```javascript
28
-
// Not accessible:
29
-
constNotAccessibleButton= () => (
30
-
<RectButton onPress={this._onPress}>
31
-
<Text>Foo</Text>
32
-
</RectButton>
33
-
);
34
-
// Accessible:
35
-
constAccessibleButton= () => (
36
-
<RectButton onPress={this._onPress}>
37
-
<View accessible accessibilityRole="button">
38
-
<Text>Bar</Text>
39
-
</View>
40
-
</RectButton>
41
-
);
26
+
Can be used as a base class if you'd like to implement some custom interaction for when the button is pressed.
27
+
28
+
### onPress
29
+
30
+
```ts
31
+
onPress?: (pointerInside:boolean) =>void;
42
32
```
43
33
44
-
It is applicable for both iOS and Android platform. On iOS, you won't be able to even select the button, on Android you won't be able to click it in accessibility mode.
34
+
Triggered when the button gets pressed (analogous to `onPress`in `TouchableHighlight` from RN core).
45
35
46
-
## `BaseButton`
47
36
48
-
Can be used as a base class if you'd like to implement some custom interaction for when the button is pressed.
37
+
### onLongPress
38
+
39
+
```ts
40
+
onLongPress?: () =>void;
41
+
```
49
42
50
-
Below is a list of properties specific to `BaseButton` component:
43
+
Triggered when the button gets pressed for at least [`delayLongPress`](#delaylongpress) milliseconds.
51
44
52
-
### `onActiveStateChange`
53
45
54
-
function that gets triggered when button changes from inactive to active and vice versa. It passes active state as a boolean variable as a first parameter for that method.
46
+
### onActiveStateChange
55
47
56
-
### `onPress`
48
+
```ts
49
+
onActiveStateChange?: (active:boolean) =>void;
50
+
```
57
51
58
-
function that gets triggered when the button gets pressed (analogous to `onPress` in `TouchableHighlight` from RN core).
52
+
Triggered when the button transitions between active and inactive states. It passes the current active state as a boolean variable to the method as the first parameter.
59
53
60
-
### `onLongPress`
61
54
62
-
function that gets triggered when the button gets pressed for at least `delayLongPress` milliseconds.
55
+
### rippleColor (**Android only**)
63
56
64
-
### `rippleColor` (**Android only**)
57
+
```ts
58
+
rippleColor?:number|ColorValue|null;
59
+
```
65
60
66
-
defines color of native [ripple](https://developer.android.com/reference/android/graphics/drawable/RippleDrawable) animation used since API level 21.
61
+
Defines [color](https://reactnative.dev/docs/colors) of native [ripple](https://developer.android.com/reference/android/graphics/drawable/RippleDrawable) animation.
67
62
68
-
### `exclusive`
63
+
### exclusive
69
64
70
-
defines if more than one button could be pressed simultaneously. By default set `true`.
65
+
```ts
66
+
exclusive?:boolean;
67
+
```
71
68
72
-
### `delayLongPress`
69
+
Defines if more than one button could be pressed simultaneously. By default set to `true`.
73
70
74
-
defines the delay, in milliseconds, after which the `onLongPress` callback gets called. By default set to 600.
71
+
### delayLongPress
75
72
76
-
## `RectButton`
73
+
```ts
74
+
delayLongPress?:number;
75
+
```
77
76
78
-
This type of button component should be used when you deal with rectangular elements or blocks of content that can be pressed, for example table rows or buttons with text and icons. This component provides a platform specific interaction, rendering a rectangular ripple on Android or highlighting the background on iOS and on older versions of Android. In addition to the props of [`BaseButton`](/docs/components/buttons#basebutton), it accepts the following:
77
+
Defines the delay, in milliseconds, after which the [`onLongPress`](#onlongpress) callback gets called. By default set to `600`.
79
78
80
-
Below is a list of properties specific to `RectButton` component:
79
+
## RectButton
81
80
82
-
### `underlayColor`
81
+
This type of button component is ideal for use with rectangular elements or content blocks that can be pressed, such as table rows or buttons featuring text and icons. It ensures platform-specific interactions, such as rendering a rectangular ripple on Android or highlighting the background on iOS and older Android versions. In addition to the props offered by [`BaseButton`](#basebutton), it accepts the following:
83
82
84
-
this is the background color that will be dimmed when button is in active state.
83
+
### underlayColor
85
84
86
-
### `activeOpacity` (**iOS only**)
85
+
```ts
86
+
underlayColor?:string;
87
+
```
87
88
88
-
opacity applied to the underlay when button is in active state.
89
+
Background color that will be dimmed when button is in active state.
89
90
90
-
##`BorderlessButton`
91
+
### activeOpacity (**iOS only**)
91
92
92
-
This type of button component should be used with simple icon-only or text-only buttons. The interaction will be different depending on platform: on Android a borderless ripple will be rendered (it means that the ripple will animate into a circle that can span outside of the view bounds), whereas on iOS the button will be dimmed (similar to how `TouchableOpacity` works). In addition to the props of [`BaseButton`](/docs/components/buttons#basebutton), it accepts the following:
93
+
```ts
94
+
activeOpacity?:number;
95
+
```
96
+
97
+
Opacity applied to the underlay when button is in active state.
93
98
94
-
Below is a list of properties specific to `BorderlessButton` component:
99
+
## BorderlessButton
100
+
101
+
This type of button component should be used with simple icon-only or text-only buttons. The interaction will be different depending on platform: on Android a borderless ripple will be rendered (it means that the ripple will animate into a circle that can span outside of the view bounds), whereas on iOS the button will be dimmed (similar to how `TouchableOpacity` works). In addition to the props of [`BaseButton`](/docs/components/buttons#basebutton), it accepts the following:
95
102
96
103
### `borderless` (**Android only**)
97
104
@@ -101,21 +108,43 @@ set this to `false` if you want the ripple animation to render only within view
101
108
102
109
opacity applied to the button when it is in an active state.
103
110
111
+
## Accessibility
112
+
113
+
To guarantee that buttons are fully accessible, you must wrap your children in a `View` marked as `accessible` and include the `accessibilityRole="button"` prop. This requirement applies to both iOS and Android platforms. Without these adjustments, the button won't be selectable on iOS, and on Android, it won't be clickable in accessibility mode.
114
+
115
+
```tsx
116
+
// Not accessible:
117
+
const NotAccessibleButton = () => (
118
+
<RectButtononPress={this._onPress}>
119
+
<Text>Foo</Text>
120
+
</RectButton>
121
+
);
122
+
123
+
// Accessible:
124
+
const AccessibleButton = () => (
125
+
<RectButtononPress={this._onPress}>
126
+
<ViewaccessibleaccessibilityRole="button">
127
+
<Text>Bar</Text>
128
+
</View>
129
+
</RectButton>
130
+
);
131
+
```
132
+
104
133
## Design patterns
105
134
106
-
Components listed here were not designed to behave and look in the same way on both platforms but rather to be used for handling similar behaviour on iOS and Android taking into consideration their's design concepts.
135
+
Components listed here were not designed to behave and look in the same way on both platforms but rather to be used for handling similar behaviour on iOS and Android taking into consideration theirs design concepts.
107
136
108
137
If you wish to get specific information about platforms design patterns, visit [official Apple docs](https://developer.apple.com/design/human-interface-guidelines/components/menus-and-actions/buttons) and [Material.io guideline](https://material.io/components/buttons#text-button), which widely describe how to implement coherent design.
109
138
110
139
This library allows to use native components with native feedback in adequate situations.
111
140
112
-
If you do not wish to implement custom design approach, `RectButton` and `BorderlessButton` seem to be absolutely enough and there's no need to use anything else. In all the remaining cases you can always rely on `BaseButton` which is a superclass for the other button classes and can be used as a generic `Touchable` replacement that can be customized to your needs.
141
+
If you do not wish to implement custom design approach, [`RectButton`](#rectbutton) and [`BorderlessButton`](#borderlessbutton) seem to be absolutely enough and there's no need to use anything else. In all the remaining cases you can always rely on [`BaseButton`](#basebutton) which is a superclass for the other button classes and can be used as a generic `Touchable` replacement that can be customized to your needs.
113
142
114
143
Below we list some of the common usecases for button components to be used along with the type of button that should be used according to the platform specific design guidelines.
115
144
116
145
### Lists and action buttons
117
146
118
-
If you have a list with clickable items or have an action button that need to display as a separate UI block (vs being inlined in a text) you should use `RectButton`. It changes opacity on click and additionally supports a ripple effect on Android.
147
+
If you have a list with clickable items or have an action button that need to display as a separate UI block (vs being inlined in a text) you should use [`RectButton`](#rectbutton). It changes opacity on click and additionally supports a [ripple effect](#ripplecolor-android-only) on Android.
Use a `PureNativeButton` for accessing the native Component used for build more complex buttons listed above.
145
-
It's normally is not recommended to use, but it might be useful if we want to wrap it using Animated or Reanimated.
173
+
Use a `PureNativeButton` for accessing the host component used for build more complex buttons listed above.
174
+
Normally it is not recommended to use, but it might be useful if you want to wrap it using [Animated](https://reactnative.dev/docs/animated) or [Reanimated](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/).
0 commit comments