0
# Form Controls
1

2
Input components for forms and user data entry, including text inputs, checkboxes, radio buttons, switches, search bars, and segmented buttons.
3

4
## Capabilities
5

6
### TextInput
7

8
Primary text input component with Material Design styling and multiple modes.
9

10
```typescript { .api }
11
/**
12
 * Text input component with Material Design styling
13
 * @param props - Text input configuration
14
 * @returns JSX Element for text input
15
 */
16
function TextInput(props: TextInputProps): JSX.Element;
17

18
interface TextInputProps {
19
  /** Input mode styling */
20
  mode?: 'flat' | 'outlined';
21
  /** Input label */
22
  label?: string;
23
  /** Placeholder text */
24
  placeholder?: string;
25
  /** Current input value */
26
  value: string;
27
  /** Value change handler */
28
  onChangeText: (text: string) => void;
29
  /** Whether input has error state */
30
  error?: boolean;
31
  /** Whether input is disabled */
32
  disabled?: boolean;
33
  /** Whether input is read-only */
34
  editable?: boolean;
35
  /** Input type/keyboard */
36
  keyboardType?: 'default' | 'number-pad' | 'decimal-pad' | 'numeric' | 'email-address' | 'phone-pad' | 'url';
37
  /** Text content type for autofill */
38
  textContentType?: 'none' | 'username' | 'password' | 'emailAddress' | 'name' | 'givenName' | 'familyName' | 'addressCity' | 'addressState' | 'addressCityAndState' | 'sublocality' | 'countryName' | 'postalCode' | 'telephoneNumber' | 'creditCardNumber' | 'organizationName' | 'newPassword' | 'oneTimeCode';
39
  /** Auto capitalize behavior */
40
  autoCapitalize?: 'none' | 'sentences' | 'words' | 'characters';
41
  /** Auto complete type */
42
  autoComplete?: string;
43
  /** Whether text is secure (password) */
44
  secureTextEntry?: boolean;
45
  /** Maximum input length */
46
  maxLength?: number;
47
  /** Whether input is multiline */
48
  multiline?: boolean;
49
  /** Number of lines for multiline */
50
  numberOfLines?: number;
51
  /** Focus handler */
52
  onFocus?: (event: NativeSyntheticEvent<TextInputFocusEventData>) => void;
53
  /** Blur handler */
54
  onBlur?: (event: NativeSyntheticEvent<TextInputFocusEventData>) => void;
55
  /** Submit editing handler */
56
  onSubmitEditing?: (event: NativeSyntheticEvent<TextInputSubmitEditingEventData>) => void;
57
  /** Left icon or element */
58
  left?: React.ReactNode,
59
  /** Right icon or element */
60
  right?: React.ReactNode;
61
  /** Selection color */
62
  selectionColor?: string;
63
  /** Underline color for flat mode */
64
  underlineColor?: string;
65
  /** Active underline color for flat mode */
66
  activeUnderlineColor?: string;
67
  /** Active outline color for outlined mode */
68
  activeOutlineColor?: string;
69
  /** Outline color for outlined mode */
70
  outlineColor?: string;
71
  /** Dense mode for compact layout */ 
72
  dense?: boolean;
73
  /** Custom style */
74
  style?: StyleProp<ViewStyle>;
75
  /** Theme override */
76
  theme?: ThemeProp;
77
  /** Test ID */
78
  testID?: string;
79
  /** Content style */
80
  contentStyle?: StyleProp<TextStyle>;
81
  /** Render function for custom rendering */
82
  render?: (props: RenderProps) => React.ReactNode;
83
}
84
```
85

86
**Usage Examples:**
87

88
```typescript
89
import React, { useState } from 'react';
90
import { TextInput } from 'react-native-paper';
91

92
function MyForm() {
93
  const [email, setEmail] = useState('');
94
  const [password, setPassword] = useState('');
95
  const [showPassword, setShowPassword] = useState(false);
96

97
  return (
98
    <>
99
      <TextInput
100
        label="Email"
101
        value={email}
102
        onChangeText={setEmail}
103
        mode="outlined"
104
        keyboardType="email-address"
105
        autoComplete="email"
106
        left={<TextInput.Icon icon="email" />}
107
      />
108
      
109
      <TextInput
110
        label="Password"
111
        value={password}
112
        onChangeText={setPassword}
113
        mode="outlined"
114
        secureTextEntry={!showPassword}
115
        right={
116
          <TextInput.Icon 
117
            icon={showPassword ? "eye-off" : "eye"}
118
            onPress={() => setShowPassword(!showPassword)}
119
          />
120
        }
121
      />
122
    </>
123
  );
124
}
125
```
126

127
### TextInput Adornments
128

129
Icon and affix components for TextInput decoration.
130

131
```typescript { .api }
132
/**
133
 * Icon component for TextInput left/right adornment
134
 * @param props - Icon configuration
135
 * @returns JSX Element for text input icon
136
 */
137
namespace TextInput {
138
  function Icon(props: TextInputIconProps): JSX.Element;
139
  function Affix(props: TextInputAffixProps): JSX.Element;
140
}
141

142
interface TextInputIconProps {
143
  /** Icon source */
144
  icon: IconSource;
145
  /** Press handler */
146
  onPress?: () => void;
147
  /** Whether icon is pressable */
148
  forceTextInputFocus?: boolean;
149
  /** Icon color */
150
  color?: string;
151
  /** Custom style */
152
  style?: StyleProp<ViewStyle>;
153
  /** Theme override */
154
  theme?: ThemeProp;
155
}
156

157
interface TextInputAffixProps {
158
  /** Affix text content */
159
  text: string;
160
  /** Affix type */
161
  type: 'prefix' | 'suffix';
162
  /** Text color */
163
  textColor?: string;
164
  /** Custom style */
165
  style?: StyleProp<ViewStyle>;
166
  /** Theme override */
167
  theme?: ThemeProp;
168
}
169
```
170

171
### Searchbar
172

173
Specialized text input for search functionality with built-in search styling.
174

175
```typescript { .api }
176
/**
177
 * Search input component with search-specific styling
178
 * @param props - Searchbar configuration
179
 * @returns JSX Element for search input
180
 */
181
function Searchbar(props: SearchbarProps): JSX.Element;
182

183
interface SearchbarProps {
184
  /** Placeholder text */
185
  placeholder?: string;
186
  /** Current search value */
187
  value: string;
188
  /** Value change handler */
189
  onChangeText: (query: string) => void;
190
  /** Search icon source */
191
  icon?: IconSource;
192
  /** Search icon color */
193
  iconColor?: string;
194
  /** Custom ripple color */
195
  rippleColor?: ColorValue;
196
  /** Search submission handler */
197
  onSubmitEditing?: (event: NativeSyntheticEvent<TextInputSubmitEditingEventData>) => void;
198
  /** Focus handler */
199
  onFocus?: () => void;
200
  /** Blur handler */
201
  onBlur?: () => void;
202
  /** Clear icon press handler */
203
  onIconPress?: () => void;
204
  /** Clear button press handler */
205
  onClearIconPress?: () => void;
206
  /** Search icon accessibility label */
207
  searchAccessibilityLabel?: string;
208
  /** Clear icon accessibility label */
209
  clearAccessibilityLabel?: string;
210
  /** Custom input style */
211
  inputStyle?: StyleProp<TextStyle>;
212
  /** Custom style */
213
  style?: StyleProp<ViewStyle>;
214
  /** Theme override */
215
  theme?: ThemeProp;
216
  /** Test ID */
217
  testID?: string;
218
}
219
```
220

221
**Usage Example:**
222

223
```typescript
224
import React, { useState } from 'react';
225
import { Searchbar } from 'react-native-paper';
226

227
function SearchScreen() {
228
  const [searchQuery, setSearchQuery] = useState('');
229

230
  const onChangeSearch = (query: string) => setSearchQuery(query);
231

232
  return (
233
    <Searchbar
234
      placeholder="Search..."
235
      onChangeText={onChangeSearch}
236
      value={searchQuery}
237
      onSubmitEditing={() => performSearch(searchQuery)}
238
    />
239
  );
240
}
241
```
242

243
### Checkbox
244

245
Checkbox input component with multiple platform styles and item wrapper.
246

247
```typescript { .api }
248
/**
249
 * Checkbox input component
250
 * @param props - Checkbox configuration
251
 * @returns JSX Element for checkbox
252
 */
253
function Checkbox(props: CheckboxProps): JSX.Element;
254

255
interface CheckboxProps {
256
  /** Checkbox state */
257
  status: 'checked' | 'unchecked' | 'indeterminate';
258
  /** State change handler */
259
  onPress?: () => void;
260
  /** Whether checkbox is disabled */
261
  disabled?: boolean;
262
  /** Custom color */
263
  color?: string;
264
  /** Custom unchecked color */
265
  uncheckedColor?: string;
266
  /** Test ID */
267
  testID?: string;
268
  /** Theme override */
269
  theme?: ThemeProp;
270
}
271

272
/**
273
 * Platform-specific checkbox variants and item wrapper
274
 */
275
namespace Checkbox {
276
  function Item(props: CheckboxItemProps): JSX.Element;
277
  function Android(props: CheckboxAndroidProps): JSX.Element;
278
  function IOS(props: CheckboxIOSProps): JSX.Element;
279
}
280

281
interface CheckboxItemProps {
282
  /** Item label text */
283
  label: string;
284
  /** Checkbox state */
285
  status: 'checked' | 'unchecked' | 'indeterminate';
286
  /** State change handler */
287
  onPress?: () => void;
288
  /** Whether item is disabled */
289
  disabled?: boolean;
290
  /** Label position relative to checkbox */
291
  position?: 'leading' | 'trailing';
292
  /** Custom color */
293
  color?: string;
294
  /** Custom unchecked color */
295
  uncheckedColor?: string;
296
  /** Custom ripple color */
297
  rippleColor?: ColorValue;
298
  /** Custom label style */
299
  labelStyle?: StyleProp<TextStyle>;
300
  /** Custom style */
301
  style?: StyleProp<ViewStyle>;
302
  /** Theme override */
303
  theme?: ThemeProp;
304
  /** Test ID */
305
  testID?: string;
306
}
307

308
interface CheckboxAndroidProps extends CheckboxProps {
309
  /** Android-specific styling */
310
}
311

312
interface CheckboxIOSProps extends CheckboxProps {
313
  /** iOS-specific styling */
314
}
315
```
316

317
**Usage Examples:**
318

319
```typescript
320
import React, { useState } from 'react';
321
import { Checkbox } from 'react-native-paper';
322

323
function CheckboxExample() {
324
  const [checked, setChecked] = useState(false);
325

326
  return (
327
    <>
328
      {/* Basic checkbox */}
329
      <Checkbox
330
        status={checked ? 'checked' : 'unchecked'}
331
        onPress={() => setChecked(!checked)}
332
      />
333

334
      {/* Checkbox with label */}
335
      <Checkbox.Item
336
        label="Accept terms and conditions"
337
        status={checked ? 'checked' : 'unchecked'}
338
        onPress={() => setChecked(!checked)}
339
      />
340

341
      {/* Platform-specific checkboxes */}
342
      <Checkbox.Android
343
        status={checked ? 'checked' : 'unchecked'}
344
        onPress={() => setChecked(!checked)}
345
      />
346
    </>
347
  );
348
}
349
```
350

351
### RadioButton
352

353
Radio button input for single selection from multiple options.
354

355
```typescript { .api }
356
/**
357
 * Radio button input component
358
 * @param props - Radio button configuration
359
 * @returns JSX Element for radio button
360
 */
361
function RadioButton(props: RadioButtonProps): JSX.Element;
362

363
interface RadioButtonProps {
364
  /** Radio button value */
365
  value: string;
366
  /** Current selected value */
367
  status?: 'checked' | 'unchecked';
368
  /** Whether radio button is disabled */
369
  disabled?: boolean;
370
  /** Press handler */
371
  onPress?: () => void;
372
  /** Custom color */
373
  color?: string;
374
  /** Custom unchecked color */
375
  uncheckedColor?: string;
376
  /** Test ID */
377
  testID?: string;
378
  /** Theme override */
379
  theme?: ThemeProp;
380
}
381

382
/**
383
 * Radio button variants and group components
384
 */
385
namespace RadioButton {
386
  function Group(props: RadioButtonGroupProps): JSX.Element;
387
  function Item(props: RadioButtonItemProps): JSX.Element;
388
  function Android(props: RadioButtonAndroidProps): JSX.Element;
389
  function IOS(props: RadioButtonIOSProps): JSX.Element;
390
}
391

392
interface RadioButtonGroupProps {
393
  /** Current selected value */
394
  value: string;
395
  /** Value change handler */
396
  onValueChange: (value: string) => void;
397
  /** Group content */
398
  children: React.ReactNode;
399
}
400

401
interface RadioButtonItemProps {
402
  /** Item label text */
403
  label: string;
404
  /** Radio button value */
405
  value: string;
406
  /** Current selected value */
407
  status?: 'checked' | 'unchecked';
408
  /** Whether item is disabled */
409
  disabled?: boolean;
410
  /** State change handler */
411
  onPress?: () => void;
412
  /** Label position */
413
  position?: 'leading' | 'trailing';
414
  /** Custom color */
415
  color?: string;
416
  /** Custom unchecked color */
417
  uncheckedColor?: string;
418
  /** Custom label style */
419
  labelStyle?: StyleProp<TextStyle>;
420
  /** Custom style */
421
  style?: StyleProp<ViewStyle>;
422
  /** Theme override */
423
  theme?: ThemeProp;
424
  /** Test ID */
425
  testID?: string;
426
}
427

428
interface RadioButtonAndroidProps extends RadioButtonProps {
429
  /** Android-specific styling */
430
}
431

432
interface RadioButtonIOSProps extends RadioButtonProps {
433
  /** iOS-specific styling */
434
}
435
```
436

437
**Usage Examples:**
438

439
```typescript
440
import React, { useState } from 'react';
441
import { RadioButton } from 'react-native-paper';
442

443
function RadioExample() {
444
  const [value, setValue] = useState('first');
445

446
  return (
447
    <RadioButton.Group onValueChange={setValue} value={value}>
448
      <RadioButton.Item label="First option" value="first" />
449
      <RadioButton.Item label="Second option" value="second" />
450
      <RadioButton.Item label="Third option" value="third" />
451
    </RadioButton.Group>
452
  );
453
}
454
```
455

456
### Switch
457

458
Toggle switch component for binary settings.
459

460
```typescript { .api }
461
/**
462
 * Toggle switch component
463
 * @param props - Switch configuration  
464
 * @returns JSX Element for switch
465
 */
466
function Switch(props: SwitchProps): JSX.Element;
467

468
interface SwitchProps {
469
  /** Whether switch is on */
470
  value: boolean;
471
  /** Value change handler */
472
  onValueChange?: (value: boolean) => void;
473
  /** Whether switch is disabled */
474
  disabled?: boolean;
475
  /** Custom thumb color */
476
  thumbColor?: string;
477
  /** Custom track color */
478
  trackColor?: {
479
    false?: string;
480
    true?: string;
481
  };
482
  /** iOS thumb color */
483
  ios_backgroundColor?: string;
484
  /** Test ID */
485
  testID?: string;
486
  /** Custom style */
487
  style?: StyleProp<ViewStyle>;
488
  /** Theme override */
489
  theme?: ThemeProp;
490
}
491
```
492

493
**Usage Example:**
494

495
```typescript
496
import React, { useState } from 'react';
497
import { Switch } from 'react-native-paper';
498

499
function SwitchExample() {
500
  const [isSwitchOn, setIsSwitchOn] = useState(false);
501

502
  const onToggleSwitch = () => setIsSwitchOn(!isSwitchOn);
503

504
  return (
505
    <Switch value={isSwitchOn} onValueChange={onToggleSwitch} />
506
  );
507
}
508
```
509

510
### SegmentedButtons
511

512
Group of buttons for single selection from multiple options.
513

514
```typescript { .api }
515
/**
516
 * Segmented button group for single selection
517
 * @param props - Segmented buttons configuration
518
 * @returns JSX Element for segmented buttons
519
 */
520
function SegmentedButtons(props: SegmentedButtonsProps): JSX.Element;
521

522
interface SegmentedButtonsProps {
523
  /** Array of button configurations */
524
  buttons: Array<{
525
    value: string;
526
    label?: string;
527
    icon?: IconSource;
528
    disabled?: boolean;
529
    accessibilityLabel?: string;
530
    testID?: string;
531
    showSelectedCheck?: boolean;
532
    style?: StyleProp<ViewStyle>;
533
    labelStyle?: StyleProp<TextStyle>;
534
    onPress?: () => void;
535
  }>;
536
  /** Current selected value */
537
  value: string;
538
  /** Value change handler */
539
  onValueChange: (value: string) => void;
540
  /** Density mode */
541
  density?: 'regular' | 'small' | 'medium' | 'high';
542
  /** Whether buttons are multiline */
543
  multiSelect?: boolean;
544
  /** Custom style */
545
  style?: StyleProp<ViewStyle>;
546
  /** Theme override */
547
  theme?: ThemeProp;
548
}
549
```
550

551
**Usage Example:**
552

553
```typescript
554
import React, { useState } from 'react';
555
import { SegmentedButtons } from 'react-native-paper';
556

557
function SegmentedExample() {
558
  const [value, setValue] = useState('');
559

560
  return (
561
    <SegmentedButtons
562
      value={value}
563
      onValueChange={setValue}
564
      buttons={[
565
        {
566
          value: 'walk',
567
          label: 'Walking',
568
          icon: 'walk',
569
        },
570
        {
571
          value: 'train',
572
          label: 'Transit',
573
          icon: 'train',
574
        },
575
        {
576
          value: 'drive',
577
          label: 'Driving',
578
          icon: 'car',
579
        },
580
      ]}
581
    />
582
  );
583
}
584
```
585

586
### HelperText
587

588
Helper text component for providing additional context to form inputs.
589

590
```typescript { .api }
591
/**
592
 * Helper text component for form inputs
593
 * @param props - Helper text configuration
594
 * @returns JSX Element for helper text
595
 */
596
function HelperText(props: HelperTextProps): JSX.Element;
597

598
interface HelperTextProps {
599
  /** Helper text type */
600
  type: 'error' | 'info';
601
  /** Whether helper text is visible */
602
  visible?: boolean;
603
  /** Helper text content */
604
  children: React.ReactNode;
605
  /** Custom text color */
606
  color?: string;
607
  /** Text padding */
608
  padding?: 'none' | 'normal';
609
  /** Custom style */
610
  style?: StyleProp<ViewStyle>;
611
  /** Theme override */
612
  theme?: ThemeProp;
613
}
614
```
615

616
**Usage Example:**
617

618
```typescript
619
import React, { useState } from 'react';
620
import { TextInput, HelperText } from 'react-native-paper';
621

622
function FormWithHelper() {
623
  const [email, setEmail] = useState('');
624
  const [hasError, setHasError] = useState(false);
625

626
  const onChangeText = (text: string) => {
627
    setEmail(text);
628
    setHasError(!text.includes('@'));
629
  };
630

631
  return (
632
    <>
633
      <TextInput
634
        label="Email"
635
        value={email}
636
        onChangeText={onChangeText}
637
        error={hasError}
638
      />
639
      <HelperText type="error" visible={hasError}>
640
        Email address is invalid!
641
      </HelperText>
642
    </>
643
  );
644
}
645
```
646

647
## Types
648

649
```typescript { .api }
650
interface NativeSyntheticEvent<T> {
651
  // React Native synthetic event type
652
}
653

654
interface TextInputFocusEventData {
655
  // React Native text input focus event data
656
}
657

658
interface TextInputSubmitEditingEventData {
659
  // React Native text input submit event data
660
}
661

662
interface RenderProps {
663
  // Custom render props for TextInput
664
}
665

666
type ColorValue = string | number;
667
```