0
# Core Picker Component
1

2
Main cross-platform picker component that automatically renders the appropriate platform-specific implementation based on `Platform.OS`. Provides a unified API across iOS, Android, macOS, and Windows platforms.
3

4
## Capabilities
5

6
### Picker Class
7

8
The main `Picker` component with full TypeScript generics support for type-safe value handling.
9

10
```typescript { .api }
11
/**
12
 * Cross-platform picker component for React Native
13
 * Automatically renders platform-appropriate implementation
14
 */
15
declare class Picker<T = ItemValue> extends React.Component<PickerProps<T>, {}> {
16
  /** Android dialog display mode constant */
17
  static readonly MODE_DIALOG: 'dialog';
18
  /** Android dropdown display mode constant */
19
  static readonly MODE_DROPDOWN: 'dropdown';
20
  /** Reference to PickerItem component */
21
  static Item: React.ComponentType<PickerItemProps<T>>;
22
  
23
  /** Programmatically opens picker (Android only) */
24
  focus: () => void;
25
  /** Programmatically closes picker (Android only) */
26
  blur: () => void;
27
}
28

29
interface PickerProps<T = ItemValue> extends ViewProps {
30
  /** Currently selected value matching an item's value */
31
  selectedValue?: T;
32
  /** Callback when an item is selected */
33
  onValueChange?: (itemValue: T, itemIndex: number) => void;
34
  /** Component styling */
35
  style?: StyleProp<TextStyle>;
36
  /** Enable/disable picker interaction (Android, Web, Windows) */
37
  enabled?: boolean;
38
  /** Display mode for Android picker */
39
  mode?: 'dialog' | 'dropdown';
40
  /** Style for individual item labels (iOS, Windows) */
41
  itemStyle?: StyleProp<TextStyle>;
42
  /** Selection indicator color (iOS) */
43
  selectionColor?: ColorValue;
44
  /** Dialog title text (Android) */
45
  prompt?: string;
46
  /** Placeholder text when no item selected (Windows) */
47
  placeholder?: string;
48
  /** Testing identifier */
49
  testID?: string;
50
  /** Dropdown arrow color (Android) */
51
  dropdownIconColor?: number | ColorValue;
52
  /** Dropdown arrow ripple color (Android) */
53
  dropdownIconRippleColor?: number | ColorValue;
54
  /** Maximum lines for text truncation (Android, iOS) */
55
  numberOfLines?: number;
56
  /** Accessibility label for screen readers */
57
  accessibilityLabel?: string;
58
  /** Focus event handler (Android) */
59
  onFocus?: (e: NativeSyntheticEvent<TargetedEvent>) => void;
60
  /** Blur event handler (Android) */
61
  onBlur?: (e: NativeSyntheticEvent<TargetedEvent>) => void;
62
}
63

64
type ItemValue = number | string | object;
65
```
66

67
**Usage Examples:**
68

69
```typescript
70
import React, { useState } from "react";
71
import { Picker } from "@react-native-picker/picker";
72

73
// Basic controlled picker
74
function BasicPicker() {
75
  const [selectedValue, setSelectedValue] = useState("key1");
76
  
77
  return (
78
    <Picker
79
      selectedValue={selectedValue}
80
      onValueChange={(itemValue, itemIndex) => setSelectedValue(itemValue)}
81
    >
82
      <Picker.Item label="Option 1" value="key1" />
83
      <Picker.Item label="Option 2" value="key2" />
84
    </Picker>
85
  );
86
}
87

88
// Android dropdown mode with styling
89
function AndroidDropdown() {
90
  const [value, setValue] = useState("option1");
91
  
92
  return (
93
    <Picker
94
      selectedValue={value}
95
      onValueChange={setValue}
96
      mode="dropdown"
97
      enabled={true}
98
      prompt="Select an option"
99
      dropdownIconColor="#FF6B6B"
100
      numberOfLines={2}
101
    >
102
      <Picker.Item label="First Option" value="option1" />
103
      <Picker.Item label="Second Option" value="option2" />
104
    </Picker>
105
  );
106
}
107

108
// Programmatic control (Android)
109
function ControlledPicker() {
110
  const pickerRef = useRef<Picker>(null);
111
  const [value, setValue] = useState("default");
112
  
113
  const openPicker = () => pickerRef.current?.focus();
114
  const closePicker = () => pickerRef.current?.blur();
115
  
116
  return (
117
    <>
118
      <Picker
119
        ref={pickerRef}
120
        selectedValue={value}
121
        onValueChange={setValue}
122
        onFocus={() => console.log("Picker opened")}
123
        onBlur={() => console.log("Picker closed")}
124
      >
125
        <Picker.Item label="Default" value="default" />
126
        <Picker.Item label="Other" value="other" />
127
      </Picker>
128
      <Button title="Open Picker" onPress={openPicker} />
129
    </>
130
  );
131
}
132
```
133

134
### Event Handling
135

136
The picker provides comprehensive event handling for user interactions and programmatic control.
137

138
```typescript { .api }
139
/**
140
 * Value change callback with selected item information
141
 * @param itemValue - The value prop of the selected item
142
 * @param itemIndex - Zero-based index of selected item
143
 */
144
onValueChange?: (itemValue: T, itemIndex: number) => void;
145

146
/**
147
 * Focus event fired when picker becomes active (Android only)
148
 * @param event - Native synthetic event with target information
149
 */
150
onFocus?: (e: NativeSyntheticEvent<TargetedEvent>) => void;
151

152
/**
153
 * Blur event fired when picker loses focus (Android only)
154
 * @param event - Native synthetic event with target information
155
 */
156
onBlur?: (e: NativeSyntheticEvent<TargetedEvent>) => void;
157
```
158

159
### Mode Constants
160

161
Constants for Android picker display modes.
162

163
```typescript { .api }
164
/** Display picker items in a modal dialog (Android default) */
165
static readonly MODE_DIALOG: 'dialog';
166

167
/** Display picker items in a dropdown anchored to picker view (Android) */
168
static readonly MODE_DROPDOWN: 'dropdown';
169
```
170

171
### Instance Methods
172

173
Methods for programmatic picker control, available on Android platform only.
174

175
```typescript { .api }
176
/**
177
 * Programmatically opens the picker interface
178
 * Available on Android platform only
179
 */
180
focus(): void;
181

182
/**
183
 * Programmatically closes the picker interface
184
 * Available on Android platform only
185
 */
186
blur(): void;
187
```