0
# Button Components
1

2
High-performance button components with native feedback and gesture support for creating interactive UI elements.
3

4
## Capabilities
5

6
### BaseButton
7

8
Foundation button component providing core gesture handling capabilities. All other button components extend from BaseButton.
9

10
```typescript { .api }
11
/**
12
 * Base button component with gesture handling capabilities
13
 * Provides core press, long press, and active state functionality
14
 */
15
function BaseButton(props: {
16
  onPress?: (pointerInside: boolean) => void;
17
  onLongPress?: () => void;
18
  onActiveStateChange?: (active: boolean) => void;
19
  delayLongPress?: number;
20
  children?: React.ReactNode;
21
  style?: StyleProp<ViewStyle>;
22
  testID?: string;
23
  accessible?: boolean;
24
  accessibilityLabel?: string;
25
}): JSX.Element;
26

27
interface BaseButtonProps {
28
  onPress?: (pointerInside: boolean) => void;
29
  onLongPress?: () => void;
30
  onActiveStateChange?: (active: boolean) => void;
31
  delayLongPress?: number;
32
  children?: React.ReactNode;
33
  style?: StyleProp<ViewStyle>;
34
  testID?: string;
35
  accessible?: boolean;
36
  accessibilityLabel?: string;
37
}
38
```
39

40
**Usage Example:**
41

42
```typescript
43
import React from "react";
44
import { Text } from "react-native";
45
import { BaseButton } from "react-native-gesture-handler";
46

47
function MyButton() {
48
  return (
49
    <BaseButton
50
      onPress={(pointerInside) => {
51
        console.log(`Button pressed, pointer inside: ${pointerInside}`);
52
      }}
53
      onLongPress={() => {
54
        console.log("Button long pressed");
55
      }}
56
      onActiveStateChange={(active) => {
57
        console.log(`Button active state: ${active}`);
58
      }}
59
      delayLongPress={800}
60
      style={{
61
        padding: 10,
62
        backgroundColor: "lightblue",
63
        borderRadius: 5,
64
      }}
65
    >
66
      <Text>Press me</Text>
67
    </BaseButton>
68
  );
69
}
70
```
71

72
### RectButton
73

74
Rectangular button with underlay effect, ideal for list items and card-based interfaces.
75

76
```typescript { .api }
77
/**
78
 * Rectangular button with underlay color effect
79
 * Shows background color change when pressed
80
 */
81
function RectButton(props: BaseButtonProps & {
82
  underlayColor?: string;
83
  activeOpacity?: number; // iOS only
84
}): JSX.Element;
85

86
interface RectButtonProps extends BaseButtonProps {
87
  underlayColor?: string;
88
  activeOpacity?: number; // iOS only
89
}
90
```
91

92
**Usage Example:**
93

94
```typescript
95
import React from "react";
96
import { Text, View } from "react-native";
97
import { RectButton } from "react-native-gesture-handler";
98

99
function ListItem() {
100
  return (
101
    <RectButton
102
      onPress={() => console.log("List item pressed")}
103
      underlayColor="#e0e0e0"
104
      activeOpacity={0.8}
105
      style={{
106
        padding: 15,
107
        backgroundColor: "white",
108
        borderBottomWidth: 1,
109
        borderBottomColor: "#f0f0f0",
110
      }}
111
    >
112
      <View style={{ flexDirection: "row", alignItems: "center" }}>
113
        <Text style={{ fontSize: 16 }}>List Item Title</Text>
114
      </View>
115
    </RectButton>
116
  );
117
}
118
```
119

120
### BorderlessButton
121

122
Borderless button with opacity effect, perfect for icon buttons and minimal interfaces.
123

124
```typescript { .api }
125
/**
126
 * Borderless button with opacity effect
127
 * Shows opacity change when pressed, ideal for icon buttons
128
 */
129
function BorderlessButton(props: BaseButtonProps & {
130
  activeOpacity?: number; // iOS only
131
}): JSX.Element;
132

133
interface BorderlessButtonProps extends BaseButtonProps {
134
  activeOpacity?: number; // iOS only
135
}
136
```
137

138
**Usage Example:**
139

140
```typescript
141
import React from "react";
142
import { Text } from "react-native";
143
import { BorderlessButton } from "react-native-gesture-handler";
144

145
function IconButton() {
146
  return (
147
    <BorderlessButton
148
      onPress={() => console.log("Icon button pressed")}
149
      activeOpacity={0.6}
150
      style={{
151
        padding: 8,
152
        borderRadius: 20,
153
      }}
154
    >
155
      <Text style={{ fontSize: 20 }}>⚙️</Text>
156
    </BorderlessButton>
157
  );
158
}
159
```
160

161
### RawButton
162

163
Low-level button component providing direct access to native button properties, particularly useful for Android ripple effects.
164

165
```typescript { .api }
166
/**
167
 * Raw native button component with platform-specific properties
168
 * Provides direct access to native button features like Android ripple
169
 */
170
function RawButton(props: {
171
  onPress?: (pointerInside: boolean) => void;
172
  onLongPress?: () => void;
173
  onActiveStateChange?: (active: boolean) => void;
174
  delayLongPress?: number;
175
  exclusive?: boolean;
176
  rippleColor?: string; // Android only
177
  rippleRadius?: number; // Android only
178
  borderless?: boolean; // Android only
179
  foreground?: boolean; // Android only
180
  touchSoundDisabled?: boolean; // Android only
181
  children?: React.ReactNode;
182
  style?: StyleProp<ViewStyle>;
183
  testID?: string;
184
}): JSX.Element;
185

186
interface RawButtonProps {
187
  onPress?: (pointerInside: boolean) => void;
188
  onLongPress?: () => void;
189
  onActiveStateChange?: (active: boolean) => void;
190
  delayLongPress?: number;
191
  exclusive?: boolean;
192
  rippleColor?: string; // Android only
193
  rippleRadius?: number; // Android only
194
  borderless?: boolean; // Android only
195
  foreground?: boolean; // Android only
196
  touchSoundDisabled?: boolean; // Android only
197
  children?: React.ReactNode;
198
  style?: StyleProp<ViewStyle>;
199
  testID?: string;
200
}
201
```
202

203
**Usage Example:**
204

205
```typescript
206
import React from "react";
207
import { Text, Platform } from "react-native";
208
import { RawButton } from "react-native-gesture-handler";
209

210
function AndroidRippleButton() {
211
  return (
212
    <RawButton
213
      onPress={() => console.log("Raw button pressed")}
214
      rippleColor={Platform.OS === "android" ? "rgba(0,0,0,0.2)" : undefined}
215
      rippleRadius={Platform.OS === "android" ? 25 : undefined}
216
      borderless={Platform.OS === "android" ? false : undefined}
217
      foreground={Platform.OS === "android" ? true : undefined}
218
      style={{
219
        padding: 12,
220
        backgroundColor: "lightgreen",
221
        borderRadius: 6,
222
      }}
223
    >
224
      <Text>Android Ripple Button</Text>
225
    </RawButton>
226
  );
227
}
228
```
229

230
### PureNativeButton
231

232
Alias for the native gesture handler button component, providing the purest native button experience.
233

234
```typescript { .api }
235
/**
236
 * Pure native button component
237
 * Alias for the native gesture handler button implementation
238
 */
239
const PureNativeButton: typeof RawButton;
240
```
241

242
## Button Behavior
243

244
### Press Detection
245

246
All button components provide sophisticated press detection:
247

248
- **onPress**: Called when the button is pressed and released
249
- **pointerInside**: Boolean parameter indicating if the pointer was inside the button bounds when released
250
- **onLongPress**: Called when the button is held for the specified duration
251
- **onActiveStateChange**: Called when the button enters or exits the active (pressed) state
252

253
### Platform Differences
254

255
**iOS:**
256
- `activeOpacity` controls the opacity when the button is pressed
257
- Native UIButton-like behavior with touch feedback
258
- Respects iOS accessibility settings
259

260
**Android:**
261
- Ripple effects available through `rippleColor`, `rippleRadius`, `borderless`, and `foreground` props
262
- Material Design-compliant touch feedback
263
- Support for foreground and background ripples
264

265
**Web:**
266
- CSS-based hover and active states
267
- Keyboard navigation support
268
- Focus management for accessibility
269

270
### Performance Characteristics
271

272
Button components are optimized for high performance:
273

274
- **Native Thread**: Press detection runs on the native UI thread
275
- **No JavaScript Bridge**: Touch events don't cross the JavaScript bridge during interaction
276
- **Smooth Animations**: Integrates seamlessly with react-native-reanimated for smooth transitions
277
- **Memory Efficient**: Minimal memory footprint for large lists of buttons
278

279
### Accessibility
280

281
All button components support comprehensive accessibility:
282

283
```typescript
284
// Accessibility props available on all button components
285
interface AccessibilityProps {
286
  accessible?: boolean;
287
  accessibilityLabel?: string;
288
  accessibilityHint?: string;
289
  accessibilityRole?: string;
290
  accessibilityState?: { disabled?: boolean; selected?: boolean };
291
  testID?: string;
292
}
293
```
294

295
### Integration with Lists
296

297
Button components are particularly well-suited for use in lists:
298

299
```typescript
300
import React from "react";
301
import { FlatList, Text, View } from "react-native";
302
import { RectButton } from "react-native-gesture-handler";
303

304
const data = [
305
  { id: "1", title: "Item 1" },
306
  { id: "2", title: "Item 2" },
307
  { id: "3", title: "Item 3" },
308
];
309

310
function ButtonList() {
311
  const renderItem = ({ item }) => (
312
    <RectButton
313
      onPress={() => console.log(`Pressed ${item.title}`)}
314
      underlayColor="#f0f0f0"
315
      style={{
316
        padding: 15,
317
        backgroundColor: "white",
318
        borderBottomWidth: 1,
319
        borderBottomColor: "#e0e0e0",
320
      }}
321
    >
322
      <Text>{item.title}</Text>
323
    </RectButton>
324
  );
325

326
  return (
327
    <FlatList
328
      data={data}
329
      renderItem={renderItem}
330
      keyExtractor={(item) => item.id}
331
    />
332
  );
333
}
334
```