0
# Buttons & Actions
1

2
Interactive components for user actions including buttons, floating action buttons, icon buttons, and touchable elements with Material Design styling.
3

4
## Capabilities
5

6
### Button
7

8
Primary button component with multiple modes following Material Design guidelines.
9

10
```typescript { .api }
11
/**
12
 * Button component with Material Design styling
13
 * @param props - Button configuration and content
14
 * @returns JSX Element for the button
15
 */
16
function Button(props: ButtonProps): JSX.Element;
17

18
interface ButtonProps {
19
  /** Button styling mode */
20
  mode?: 'text' | 'outlined' | 'contained' | 'elevated' | 'contained-tonal';
21
  /** Button content/label */
22
  children: React.ReactNode;
23
  /** Press handler function */
24
  onPress?: (event: GestureResponderEvent) => void;
25
  /** Whether button is disabled */
26
  disabled?: boolean;
27
  /** Whether to show loading spinner */
28
  loading?: boolean;
29
  /** Icon to display in button */
30
  icon?: IconSource;
31
  /** Use compact styling */
32
  compact?: boolean;
33
  /** Custom background color */
34
  buttonColor?: string;
35
  /** Custom text color */
36
  textColor?: string;
37
  /** Make label text uppercase */
38
  uppercase?: boolean;
39
  /** Custom ripple color */
40
  rippleColor?: ColorValue;
41
  /** Whether color is dark (affects text color) */
42
  dark?: boolean;
43
  /** Accessibility label */
44
  accessibilityLabel?: string;
45
  /** Accessibility hint */
46
  accessibilityHint?: string;
47
  /** Accessibility role */
48
  accessibilityRole?: AccessibilityRole;
49
  /** Test ID for testing */
50
  testID?: string;
51
  /** Long press handler */
52
  onLongPress?: (event: GestureResponderEvent) => void;
53
  /** Press in handler */
54
  onPressIn?: (event: GestureResponderEvent) => void;
55
  /** Press out handler */
56
  onPressOut?: (event: GestureResponderEvent) => void;
57
  /** Custom style */
58
  style?: StyleProp<ViewStyle>;
59
  /** Custom content style */
60
  contentStyle?: StyleProp<ViewStyle>;
61
  /** Custom label style */
62
  labelStyle?: StyleProp<TextStyle>;
63
  /** Theme override */
64
  theme?: ThemeProp;
65
}
66
```
67

68
**Usage Examples:**
69

70
```typescript
71
import React from 'react';
72
import { Button } from 'react-native-paper';
73

74
// Basic button
75
<Button mode="contained" onPress={() => console.log('Pressed')}>
76
  Press me
77
</Button>
78

79
// Button with icon
80
<Button mode="outlined" icon="camera" onPress={handlePress}>
81
  Take Photo
82
</Button>
83

84
// Loading button
85
<Button mode="contained" loading={isLoading} disabled={isLoading}>
86
  {isLoading ? 'Loading...' : 'Submit'}
87
</Button>
88

89
// Custom styled button
90
<Button 
91
  mode="contained-tonal" 
92
  buttonColor="#6200EE" 
93
  textColor="white"
94
  contentStyle={{ height: 50 }}
95
>
96
  Custom Button
97
</Button>
98
```
99

100
### IconButton
101

102
Button component that displays only an icon, useful for toolbars and compact layouts.
103

104
```typescript { .api }
105
/**
106
 * Button component that displays only an icon
107
 * @param props - Icon button configuration
108
 * @returns JSX Element for the icon button
109
 */
110
function IconButton(props: IconButtonProps): JSX.Element;
111

112
interface IconButtonProps {
113
  /** Icon to display */
114
  icon: IconSource;
115
  /** Icon size */
116
  size?: number;
117
  /** Icon color */
118
  iconColor?: string;
119
  /** Press handler */
120
  onPress?: (event: GestureResponderEvent) => void;
121
  /** Whether button is disabled */
122
  disabled?: boolean;
123
  /** Button mode styling */
124
  mode?: 'text' | 'outlined' | 'contained' | 'contained-tonal';
125
  /** Custom container color */
126
  containerColor?: string;
127
  /** Custom ripple color */
128
  rippleColor?: ColorValue;
129
  /** Whether button is selected (toggle state) */
130
  selected?: boolean;
131
  /** Accessibility label */
132
  accessibilityLabel?: string;
133
  /** Test ID */
134
  testID?: string;
135
  /** Long press handler */
136
  onLongPress?: (event: GestureResponderEvent) => void;
137
  /** Custom style */
138
  style?: StyleProp<ViewStyle>;
139
  /** Theme override */
140
  theme?: ThemeProp;
141
}
142
```
143

144
**Usage Examples:**
145

146
```typescript
147
import React from 'react';
148
import { IconButton } from 'react-native-paper';
149

150
// Basic icon button
151
<IconButton icon="heart" onPress={() => console.log('Liked')} />
152

153
// Styled icon button
154
<IconButton 
155
  icon="share" 
156
  mode="contained"
157
  containerColor="#E1F5FE"
158
  iconColor="#0277BD"
159
  size={24}
160
  onPress={handleShare}
161
/>
162

163
// Toggle icon button
164
<IconButton 
165
  icon={isFavorite ? "heart" : "heart-outline"}
166
  selected={isFavorite}
167
  onPress={() => setIsFavorite(!isFavorite)}
168
/>
169
```
170

171
### Floating Action Button (FAB)
172

173
Prominent circular button for primary actions, typically positioned at the bottom-right of the screen.
174

175
```typescript { .api }
176
/**
177
 * Floating Action Button component
178
 * @param props - FAB configuration
179
 * @returns JSX Element for the FAB
180
 */
181
function FAB(props: FABProps): JSX.Element;
182

183
interface FABProps {
184
  /** Icon to display in FAB */
185
  icon: IconSource;
186
  /** Press handler */
187
  onPress?: (event: GestureResponderEvent) => void;
188
  /** FAB size variant */
189
  size?: 'small' | 'medium' | 'large';
190
  /** FAB mode/style variant */
191
  mode?: 'surface' | 'primary' | 'secondary' | 'tertiary';
192
  /** Whether FAB is disabled */
193
  disabled?: boolean;
194
  /** Loading state */
195
  loading?: boolean;
196
  /** Optional label text */
197
  label?: string;
198
  /** Whether FAB is extended (with label) */
199
  extended?: boolean;
200
  /** Custom background color */
201
  color?: string;
202
  /** Custom ripple color */
203
  rippleColor?: ColorValue;
204
  /** Custom icon color */
205
  customSize?: number;
206
  /** Accessibility label */
207
  accessibilityLabel?: string;
208
  /** Test ID */
209
  testID?: string;
210
  /** Long press handler */
211
  onLongPress?: (event: GestureResponderEvent) => void;
212
  /** Custom style */
213
  style?: StyleProp<ViewStyle>;
214
  /** Theme override */
215
  theme?: ThemeProp;
216
}
217
```
218

219
**Usage Examples:**
220

221
```typescript
222
import React from 'react';
223
import { FAB } from 'react-native-paper';
224

225
// Basic FAB
226
<FAB icon="plus" onPress={() => addItem()} />
227

228
// Extended FAB with label
229
<FAB 
230
  icon="plus" 
231
  label="Add Item"
232
  extended
233
  onPress={handleAdd}
234
/>
235

236
// Small FAB
237
<FAB 
238
  icon="edit" 
239
  size="small"
240
  onPress={handleEdit}
241
  style={{ position: 'absolute', bottom: 16, right: 16 }}
242
/>
243

244
// Custom styled FAB
245
<FAB 
246
  icon="camera"
247
  mode="primary"
248
  color="#FF5722"
249
  size="large"
250
  onPress={takePicture}
251
/>
252
```
253

254
### FAB Group
255

256
Container for multiple related FABs that can expand/collapse.
257

258
```typescript { .api }
259
/**
260
 * FAB Group component for multiple related actions
261
 * @param props - FAB Group configuration
262
 * @returns JSX Element for the FAB group
263
 */
264
namespace FAB {
265
  function Group(props: FABGroupProps): JSX.Element;
266
}
267

268
interface FABGroupProps {
269
  /** Whether the group is open */
270
  open: boolean;
271
  /** Handler for open/close state changes */
272
  onStateChange: (state: { open: boolean }) => void;
273
  /** Icon for the main FAB */
274
  icon: IconSource;
275
  /** Array of action FABs */
276
  actions: Array<{
277
    icon: IconSource;
278
    label?: string;
279
    onPress: () => void;
280
    color?: string;
281
    accessibilityLabel?: string;
282
    testID?: string;
283
    size?: 'small' | 'medium';
284
    disabled?: boolean;
285
    style?: StyleProp<ViewStyle>;
286
  }>;
287
  /** Color of the main FAB */
288
  color?: string;
289
  /** Custom backdrop color */
290
  backdropColor?: string;
291
  /** Custom ripple color */
292
  rippleColor?: ColorValue;
293
  /** Accessibility label for main FAB */
294
  accessibilityLabel?: string;
295
  /** Test ID */
296
  testID?: string;
297
  /** Custom style for main FAB */
298
  fabStyle?: StyleProp<ViewStyle>;
299
  /** Custom style for container */
300
  style?: StyleProp<ViewStyle>;
301
  /** Theme override */
302
  theme?: ThemeProp;
303
}
304
```
305

306
**Usage Example:**
307

308
```typescript
309
import React, { useState } from 'react';
310
import { FAB } from 'react-native-paper';
311

312
function MyComponent() {
313
  const [open, setOpen] = useState(false);
314

315
  return (
316
    <FAB.Group
317
      open={open}
318
      icon={open ? 'close' : 'plus'}
319
      actions={[
320
        {
321
          icon: 'camera',
322
          label: 'Take Photo',
323
          onPress: () => console.log('Take photo'),
324
        },
325
        {
326
          icon: 'image',
327
          label: 'Choose Image',
328
          onPress: () => console.log('Choose image'),
329
        },
330
        {
331
          icon: 'file-document',
332
          label: 'Create Document',
333
          onPress: () => console.log('Create document'),
334
        },
335
      ]}
336
      onStateChange={({ open }) => setOpen(open)}
337
    />
338
  );
339
}
340
```
341

342
### Animated FAB
343

344
FAB with entrance/exit animations and extended mode support.
345

346
```typescript { .api }
347
/**
348
 * Animated Floating Action Button with entrance/exit animations
349
 * @param props - Animated FAB configuration
350
 * @returns JSX Element for the animated FAB
351
 */
352
function AnimatedFAB(props: AnimatedFABProps): JSX.Element;
353

354
interface AnimatedFABProps {
355
  /** Icon to display */
356
  icon: IconSource;
357
  /** Optional label text */
358
  label?: string;
359
  /** Whether FAB should be extended with label */
360
  extended: boolean;
361
  /** Press handler */
362
  onPress?: (event: GestureResponderEvent) => void;
363
  /** Whether FAB is visible */
364
  visible?: boolean;
365
  /** Animation duration in ms */
366
  animateFrom?: 'left' | 'right';
367
  /** Icon color */
368
  iconColor?: string;
369
  /** Custom background color */
370
  color?: string;
371
  /** Custom ripple color */
372
  rippleColor?: ColorValue;
373
  /** Whether FAB is disabled */
374
  disabled?: boolean;
375
  /** Accessibility label */
376
  accessibilityLabel?: string;
377
  /** Test ID */
378
  testID?: string;
379
  /** Long press handler */
380
  onLongPress?: (event: GestureResponderEvent) => void;
381
  /** Custom style */
382
  style?: StyleProp<ViewStyle>;
383
  /** Theme override */
384
  theme?: ThemeProp;
385
}
386
```
387

388
**Usage Example:**
389

390
```typescript
391
import React, { useState, useEffect } from 'react';
392
import { AnimatedFAB } from 'react-native-paper';
393
import { useScrollToTop } from '@react-navigation/native';
394

395
function ScrollableScreen() {
396
  const [isExtended, setIsExtended] = useState(true);
397
  const [visible, setVisible] = useState(true);
398

399
  const onScroll = ({ nativeEvent }) => {
400
    const currentScrollPosition = Math.floor(nativeEvent?.contentOffset?.y) ?? 0;
401
    setIsExtended(currentScrollPosition <= 0);
402
  };
403

404
  return (
405
    <>
406
      <ScrollView onScroll={onScroll}>
407
        {/* Content */}
408
      </ScrollView>
409
      <AnimatedFAB
410
        icon="plus"
411
        label="Add Item"
412
        extended={isExtended}
413
        onPress={() => console.log('Add pressed')}
414
        visible={visible}
415
        animateFrom="right"
416
        style={{ bottom: 16, right: 16, position: 'absolute' }}
417
      />
418
    </>
419
  );
420
}
421
```
422

423
### TouchableRipple
424

425
Low-level touchable component with Material Design ripple effect.
426

427
```typescript { .api }
428
/**
429
 * Touchable component with Material Design ripple effect
430
 * @param props - TouchableRipple configuration
431
 * @returns JSX Element with ripple touch feedback
432
 */
433
function TouchableRipple(props: TouchableRippleProps): JSX.Element;
434

435
interface TouchableRippleProps {
436
  /** Content to make touchable */
437
  children: React.ReactNode;
438
  /** Press handler */
439
  onPress?: (event: GestureResponderEvent) => void;
440
  /** Long press handler */
441
  onLongPress?: (event: GestureResponderEvent) => void;
442
  /** Press in handler */
443
  onPressIn?: (event: GestureResponderEvent) => void;
444
  /** Press out handler */
445
  onPressOut?: (event: GestureResponderEvent) => void;
446
  /** Whether touch is disabled */
447
  disabled?: boolean;
448
  /** Color of ripple effect */
449
  rippleColor?: ColorValue;
450
  /** Color of underlay (iOS) */
451
  underlayColor?: ColorValue;
452
  /** Whether ripple is centered */
453
  centered?: boolean;
454
  /** Whether ripple is borderless */
455
  borderless?: boolean;
456
  /** Custom ripple radius */
457
  radius?: number;
458
  /** Accessibility label */
459
  accessibilityLabel?: string;
460
  /** Accessibility role */
461
  accessibilityRole?: AccessibilityRole;
462
  /** Accessibility state */
463
  accessibilityState?: {
464
    disabled?: boolean;
465
    selected?: boolean;
466
    checked?: boolean | 'mixed';
467
    busy?: boolean;
468
    expanded?: boolean;
469
  };
470
  /** Test ID */
471
  testID?: string;
472
  /** Custom style */
473
  style?: StyleProp<ViewStyle>;
474
  /** Theme override */
475
  theme?: ThemeProp;
476
}
477
```
478

479
**Usage Example:**
480

481
```typescript
482
import React from 'react';
483
import { View, Text } from 'react-native';
484
import { TouchableRipple } from 'react-native-paper';
485

486
<TouchableRipple
487
  onPress={() => console.log('Pressed')}
488
  rippleColor="rgba(0, 0, 0, .32)"
489
>
490
  <View style={{ padding: 16 }}>
491
    <Text>Custom touchable content</Text>
492
  </View>
493
</TouchableRipple>
494
```
495

496
### Toggle Button Components
497

498
Button components for selection and toggle states.
499

500
```typescript { .api }
501
/**
502
 * Toggle button for binary selection
503
 * @param props - Toggle button configuration
504
 * @returns JSX Element for toggle button
505
 */
506
function ToggleButton(props: ToggleButtonProps): JSX.Element;
507

508
interface ToggleButtonProps {
509
  /** Icon to display */
510
  icon: IconSource;
511
  /** Press handler */
512
  onPress?: () => void;
513
  /** Whether button is selected/pressed */
514
  status?: 'checked' | 'unchecked';
515
  /** Whether button is disabled */
516
  disabled?: boolean;
517
  /** Custom icon size */
518
  size?: number;
519
  /** Custom icon color */
520
  iconColor?: string;
521
  /** Ripple color */
522
  rippleColor?: ColorValue;
523
  /** Accessibility label */
524
  accessibilityLabel?: string;
525
  /** Test ID */
526
  testID?: string;
527
  /** Custom style */
528
  style?: StyleProp<ViewStyle>;
529
  /** Theme override */
530
  theme?: ThemeProp;
531
}
532

533
/**
534
 * Group of toggle buttons for multi-selection
535
 * @param props - Toggle button group configuration
536
 * @returns JSX Element for toggle button group
537
 */
538
namespace ToggleButton {
539
  function Group(props: ToggleButtonGroupProps): JSX.Element;
540
  function Row(props: ToggleButtonRowProps): JSX.Element;
541
}
542

543
interface ToggleButtonGroupProps {
544
  /** Value change handler */
545
  onValueChange: (value: string) => void;
546
  /** Currently selected value */
547
  value: string;
548
  /** Array of button configurations */
549
  buttons: Array<{
550
    value: string;
551
    icon: IconSource;
552
    disabled?: boolean;
553
    accessibilityLabel?: string;
554
    testID?: string;
555
  }>;
556
  /** Density mode */
557
  density?: 'regular' | 'medium' | 'high';
558
  /** Custom style */
559
  style?: StyleProp<ViewStyle>;
560
  /** Theme override */
561
  theme?: ThemeProp;
562
}
563

564
interface ToggleButtonRowProps {
565
  /** Multi-value change handler */
566
  onValueChange: (value: string[]) => void;
567
  /** Currently selected values */
568
  value: string[];
569
  /** Array of button configurations */
570
  buttons: Array<{
571
    value: string;
572
    icon: IconSource;
573
    disabled?: boolean;
574
    accessibilityLabel?: string;
575
    testID?: string;
576
  }>;
577
  /** Density mode */
578
  density?: 'regular' | 'medium' | 'high';
579
  /** Custom style */
580
  style?: StyleProp<ViewStyle>;
581
  /** Theme override */
582
  theme?: ThemeProp;
583
}
584
```
585

586
**Usage Examples:**
587

588
```typescript
589
import React, { useState } from 'react';
590
import { ToggleButton } from 'react-native-paper';
591

592
// Single toggle button
593
function SingleToggle() {
594
  const [status, setStatus] = useState('unchecked');
595
  
596
  return (
597
    <ToggleButton
598
      icon="heart"
599
      status={status}
600
      onPress={() => setStatus(status === 'checked' ? 'unchecked' : 'checked')}
601
    />
602
  );
603
}
604

605
// Toggle button group (single selection)
606
function ToggleGroup() {
607
  const [value, setValue] = useState('left');
608
  
609
  return (
610
    <ToggleButton.Group
611
      onValueChange={setValue}
612
      value={value}
613
      buttons={[
614
        { value: 'left', icon: 'format-align-left' },
615
        { value: 'center', icon: 'format-align-center' },
616
        { value: 'right', icon: 'format-align-right' },
617
      ]}
618
    />
619
  );
620
}
621

622
// Toggle button row (multi-selection)
623
function ToggleRow() {
624
  const [value, setValue] = useState(['bold']);
625
  
626
  return (
627
    <ToggleButton.Row
628
      onValueChange={setValue}
629
      value={value}
630
      buttons={[
631
        { value: 'bold', icon: 'format-bold' },
632
        { value: 'italic', icon: 'format-italic' },
633
        { value: 'underline', icon: 'format-underlined' },
634
      ]}
635
    />
636
  );
637
}
638
```
639

640
## Types
641

642
```typescript { .api }
643
type IconSource = string | ImageSourcePropType | {
644
  default: ImageSourcePropType;
645
} | {
646
  ios: ImageSourcePropType;
647
  android: ImageSourcePropType;
648
};
649

650
type ColorValue = string | number;
651

652
interface AccessibilityRole {
653
  // React Native accessibility role values
654
}
655

656
interface GestureResponderEvent {
657
  // React Native gesture event object
658
}
659

660
interface StyleProp<T> {
661
  // React Native style prop type
662
}
663

664
interface ViewStyle {
665
  // React Native view styles
666
}
667

668
interface TextStyle {
669
  // React Native text styles
670
}
671

672
interface ImageSourcePropType {
673
  // React Native image source type
674
}
675
```