0
# Picker Items
1

2
Individual selectable items within a Picker component. Each item represents a choice that users can select, with support for custom styling, colors, fonts, and platform-specific features.
3

4
## Capabilities
5

6
### PickerItem Component
7

8
Individual selectable items that are children of a Picker component. The render method throws null as items are processed by the parent Picker.
9

10
```typescript { .api }
11
/**
12
 * Individual selectable item in a Picker component
13
 * Items are processed by parent Picker, render method throws null
14
 */
15
interface PickerItemProps<T = ItemValue> {
16
  /** Display text shown to the user */
17
  label?: string;
18
  /** Value passed to onValueChange when selected */
19
  value?: T;
20
  /** Text color for this item (Android) */
21
  color?: string;
22
  /** Font family for this item (Android) */
23
  fontFamily?: string;
24
  /** Testing identifier for this item */
25
  testID?: string;
26
  /** Style object for this item (Android) */
27
  style?: StyleProp<TextStyle>;
28
  /** Whether this item can be selected (Android, Web) */
29
  enabled?: boolean;
30
  /** Content description for accessibility (Android) */
31
  contentDescription?: string;
32
}
33

34
/**
35
 * Picker item component class
36
 * Render method throws null as items are processed by parent
37
 */
38
class PickerItem extends React.Component<PickerItemProps> {
39
  render(): React.Node; // throws null
40
}
41
```
42

43
**Usage Examples:**
44

45
```typescript
46
import { Picker } from "@react-native-picker/picker";
47

48
// Basic items with labels and values
49
<Picker selectedValue={selectedLanguage} onValueChange={setSelectedLanguage}>
50
  <Picker.Item label="Java" value="java" />
51
  <Picker.Item label="JavaScript" value="js" />
52
  <Picker.Item label="Python" value="python" />
53
  <Picker.Item label="TypeScript" value="ts" />
54
</Picker>
55

56
// Items with custom colors (Android)
57
<Picker selectedValue={selectedColor} onValueChange={setSelectedColor}>
58
  <Picker.Item label="Red" value="red" color="#FF0000" />
59
  <Picker.Item label="Green" value="green" color="#00FF00" />
60
  <Picker.Item label="Blue" value="blue" color="#0000FF" />
61
</Picker>
62

63
// Items with custom styling (Android)
64
<Picker selectedValue={selectedFont} onValueChange={setSelectedFont}>
65
  <Picker.Item 
66
    label="Arial" 
67
    value="arial" 
68
    style={{
69
      backgroundColor: 'cyan',
70
      fontSize: 18,
71
      fontFamily: 'Arial'
72
    }}
73
  />
74
  <Picker.Item 
75
    label="Times New Roman" 
76
    value="times" 
77
    style={{
78
      backgroundColor: 'lightblue',
79
      fontSize: 16,
80
      fontFamily: 'serif'
81
    }}
82
  />
83
</Picker>
84

85
// Items with enabled/disabled states (Android, Web)
86
<Picker selectedValue={selectedOption} onValueChange={setSelectedOption}>
87
  <Picker.Item label="Available Option" value="available" enabled={true} />
88
  <Picker.Item label="Disabled Option" value="disabled" enabled={false} />
89
  <Picker.Item label="Default (Enabled)" value="default" />
90
</Picker>
91

92
// Items with test identifiers
93
<Picker selectedValue={selectedTest} onValueChange={setSelectedTest}>
94
  <Picker.Item 
95
    label="Test Option 1" 
96
    value="test1" 
97
    testID="picker-item-test1" 
98
  />
99
  <Picker.Item 
100
    label="Test Option 2" 
101
    value="test2" 
102
    testID="picker-item-test2" 
103
  />
104
</Picker>
105
```
106

107
### Item Properties
108

109
Detailed breakdown of individual item properties and their platform support.
110

111
```typescript { .api }
112
/**
113
 * Display text shown to the user in the picker
114
 * Required for meaningful user interface
115
 */
116
label?: string;
117

118
/**
119
 * Value passed to onValueChange callback when this item is selected
120
 * Can be string, number, or complex object
121
 */
122
value?: T;
123

124
/**
125
 * Text color for this specific item
126
 * Supported on Android platform only
127
 * Accepts standard React Native color values
128
 */
129
color?: string;
130

131
/**
132
 * Font family for this specific item  
133
 * Supported on Android platform only
134
 * Font file (.ttf) should be in assets/fonts directory
135
 */
136
fontFamily?: string;
137

138
/**
139
 * Testing identifier for end-to-end testing
140
 * Supported across all platforms
141
 */
142
testID?: string;
143

144
/**
145
 * Style object for individual item customization
146
 * Supported on Android platform only
147
 * Limited to: color, backgroundColor, fontSize, fontFamily
148
 */
149
style?: StyleProp<TextStyle>;
150

151
/**
152
 * Whether this item can be selected by the user
153
 * Defaults to true if not specified
154
 * Supported on Android and Web platforms
155
 */
156
enabled?: boolean;
157

158
/**
159
 * Content description for accessibility features
160
 * Used by screen readers and accessibility services
161
 * Supported on Android platform only
162
 */
163
contentDescription?: string;
164
```
165

166
### Platform-Specific Item Features
167

168
Different platforms support different item customization options.
169

170
**Android Item Features:**
171
- Custom colors via `color` prop
172
- Font family selection via `fontFamily` prop  
173
- Style objects with limited properties
174
- Individual item enable/disable via `enabled` prop
175
- Background colors via style object
176
- Accessibility support via `contentDescription` prop
177

178
**iOS Item Features:**
179
- Items inherit styling from parent Picker's `itemStyle`
180
- Limited individual customization
181
- Focus on native iOS appearance
182

183
**Windows Item Features:**  
184
- Basic label and value support
185
- Inherits styling from parent Picker
186
- Native Windows appearance
187

188
**Web Item Features:**
189
- Renders as HTML `<option>` elements
190
- Support for `enabled` prop (becomes `disabled` attribute)
191
- Basic styling through parent component
192

193
### Value Types
194

195
Items support flexible value types for different use cases.
196

197
```typescript { .api }
198
type ItemValue = number | string | object;
199

200
// String values
201
<Picker.Item label="Option A" value="option-a" />
202

203
// Numeric values  
204
<Picker.Item label="Priority 1" value={1} />
205

206
// Object values for complex data
207
<Picker.Item 
208
  label="John Doe" 
209
  value={{id: 123, name: "John Doe", email: "john@example.com"}} 
210
/>
211

212
// Boolean values
213
<Picker.Item label="Enabled" value={true} />
214
<Picker.Item label="Disabled" value={false} />
215
```