0
# React Native Picker
1

2
React Native Picker is a cross-platform picker component for React Native applications that provides dropdown/select interfaces on iOS, Android, macOS, and Windows platforms. It offers extensive customization options including item colors, fonts, selection colors, and platform-specific features like dialog/dropdown modes on Android and programmatic open/close functionality. The library maintains native performance through platform-specific implementations while providing a unified JavaScript interface.
3

4
## Package Information
5

6
- **Package Name**: @react-native-picker/picker
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript (React Native)
9
- **Installation**: `npm install @react-native-picker/picker`
10

11
## Core Imports
12

13
```typescript
14
import { Picker, PickerIOS, PickerProps, PickerItemProps } from "@react-native-picker/picker";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { Picker, PickerIOS, PickerProps, PickerItemProps } = require("@react-native-picker/picker");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import React, { useState } from "react";
27
import { Picker } from "@react-native-picker/picker";
28

29
function App() {
30
  const [selectedLanguage, setSelectedLanguage] = useState("js");
31

32
  return (
33
    <Picker
34
      selectedValue={selectedLanguage}
35
      onValueChange={(itemValue, itemIndex) => 
36
        setSelectedLanguage(itemValue)
37
      }>
38
      <Picker.Item label="Java" value="java" />
39
      <Picker.Item label="JavaScript" value="js" />
40
      <Picker.Item label="Python" value="python" />
41
    </Picker>
42
  );
43
}
44
```
45

46
## Architecture
47

48
React Native Picker is built around several key components:
49

50
- **Cross-Platform API**: Unified `Picker` component that renders platform-appropriate implementations
51
- **Platform-Specific Implementations**: Native iOS, Android, macOS, and Windows picker components
52
- **Item Components**: `Picker.Item` for defining selectable options with styling support
53
- **TypeScript Integration**: Full type safety with generic type support for values
54
- **React Native Bridge**: Native module integration for optimal performance
55

56
## Capabilities
57

58
### Core Picker Component
59

60
Main cross-platform picker component that automatically renders the appropriate platform-specific implementation. Supports controlled component pattern with extensive customization options.
61

62
```typescript { .api }
63
interface PickerProps<T = ItemValue> extends ViewProps {
64
  selectedValue?: T;
65
  onValueChange?: (itemValue: T, itemIndex: number) => void;
66
  style?: StyleProp<TextStyle>;
67
  enabled?: boolean;
68
  mode?: 'dialog' | 'dropdown';
69
  itemStyle?: StyleProp<TextStyle>;
70
  selectionColor?: ColorValue;
71
  prompt?: string;
72
  placeholder?: string;
73
  testID?: string;
74
  dropdownIconColor?: number | ColorValue;
75
  dropdownIconRippleColor?: number | ColorValue;
76
  numberOfLines?: number;
77
  accessibilityLabel?: string;
78
  onFocus?: (e: NativeSyntheticEvent<TargetedEvent>) => void;
79
  onBlur?: (e: NativeSyntheticEvent<TargetedEvent>) => void;
80
}
81

82
declare class Picker<T> extends React.Component<PickerProps<T>, {}> {
83
  static readonly MODE_DIALOG: 'dialog';
84
  static readonly MODE_DROPDOWN: 'dropdown';
85
  static Item: React.ComponentType<PickerItemProps<T>>;
86
  focus: () => void;
87
  blur: () => void;
88
}
89
```
90

91
[Core Picker](./core-picker.md)
92

93
### Picker Items
94

95
Individual selectable items within a Picker component. Support styling, colors, fonts, and platform-specific features like disabled state.
96

97
```typescript { .api }
98
interface PickerItemProps<T = ItemValue> {
99
  label?: string;
100
  value?: T;
101
  color?: string;
102
  fontFamily?: string;
103
  testID?: string;
104
  style?: StyleProp<TextStyle>;
105
  enabled?: boolean;
106
}
107
```
108

109
[Picker Items](./picker-items.md)
110

111
### iOS-Specific Picker
112

113
Enhanced picker component with iOS-specific features including theme variants, selection colors, and native iOS styling patterns.
114

115
```typescript { .api }
116
interface PickerIOSProps extends ViewProps {
117
  itemStyle?: StyleProp<TextStyle>;
118
  style?: StyleProp<TextStyle>;
119
  onChange?: React.SyntheticEvent<{itemValue: ItemValue, itemIndex: number}>;
120
  onValueChange?: (itemValue: ItemValue, itemIndex: number) => void;
121
  selectedValue?: ItemValue;
122
  testID?: string;
123
  numberOfLines?: number;
124
  themeVariant?: string;
125
}
126

127
declare class PickerIOS extends React.Component<PickerIOSProps, {}> {
128
  static Item: typeof PickerIOSItem;
129
}
130
```
131

132
[iOS Picker](./ios-picker.md)
133

134
### Platform-Specific Features
135

136
Platform-specific customization options and behaviors including Android dialog/dropdown modes, Windows placeholder support, and programmatic control methods.
137

138
```typescript { .api }
139
// Android-specific props
140
interface AndroidPickerProps {
141
  mode?: 'dialog' | 'dropdown';
142
  enabled?: boolean;
143
  prompt?: string;
144
  dropdownIconColor?: ColorValue;
145
  dropdownIconRippleColor?: ColorValue;
146
  numberOfLines?: number;
147
  onFocus?: (e: NativeSyntheticEvent<TargetedEvent>) => void;
148
  onBlur?: (e: NativeSyntheticEvent<TargetedEvent>) => void;
149
}
150

151
// Windows-specific props
152
interface WindowsPickerProps {
153
  placeholder?: string;
154
}
155

156
// iOS-specific props
157
interface IOSPickerProps {
158
  itemStyle?: StyleProp<TextStyle>;
159
  selectionColor?: ColorValue;
160
  themeVariant?: string;
161
}
162
```
163

164
[Platform Features](./platform-features.md)
165

166
## Types
167

168
```typescript { .api }
169
type ItemValue = number | string | object;
170

171
interface PickerIOSItemProps {
172
  label?: string;
173
  value?: number | string;
174
  color?: string;
175
  testID?: string;
176
}
177
```