0
# iOS Picker
1

2
Enhanced picker component with iOS-specific features including theme variants, selection colors, and native iOS styling patterns. Provides direct access to iOS-specific picker functionality beyond the cross-platform Picker component.
3

4
## Capabilities
5

6
### PickerIOS Component
7

8
iOS-specific picker component with enhanced iOS integration and styling options.
9

10
```typescript { .api }
11
/**
12
 * iOS-specific picker component with enhanced iOS features
13
 * Provides direct access to iOS native picker functionality
14
 */
15
interface PickerIOSProps extends ViewProps {
16
  /** Style to apply to each item label */
17
  itemStyle?: StyleProp<TextStyle>;
18
  /** Overall component styling */
19
  style?: StyleProp<TextStyle>;
20
  /** Change event with itemValue and itemIndex */
21
  onChange?: React.SyntheticEvent<{itemValue: ItemValue, itemIndex: number}>;
22
  /** Value change callback */
23
  onValueChange?: (itemValue: ItemValue, itemIndex: number) => void;
24
  /** Currently selected item value */
25
  selectedValue?: ItemValue;
26
  /** Testing identifier */
27
  testID?: string;
28
  /** Maximum lines for text truncation */
29
  numberOfLines?: number;
30
  /** iOS theme variant (light/dark) */
31
  themeVariant?: string;
32
}
33

34
declare class PickerIOS extends React.Component<PickerIOSProps, {}> {
35
  /** Reference to PickerIOSItem component */
36
  static Item: typeof PickerIOSItem;
37
}
38

39
interface PickerIOSItemProps {
40
  /** Display text for the item */
41
  label?: string;
42
  /** Value for the item */
43
  value?: number | string;
44
  /** Text color for the item */
45
  color?: string;
46
  /** Testing identifier */
47
  testID?: string;
48
}
49

50
declare class PickerIOSItem extends React.Component<PickerIOSItemProps, {}> {}
51
```
52

53
**Usage Examples:**
54

55
```typescript
56
import React, { useState } from "react";
57
import { PickerIOS } from "@react-native-picker/picker";
58

59
// Basic iOS picker with theme support
60
function BasicIOSPicker() {
61
  const [selectedValue, setSelectedValue] = useState("option1");
62
  
63
  return (
64
    <PickerIOS
65
      selectedValue={selectedValue}
66
      onValueChange={(itemValue, itemIndex) => setSelectedValue(itemValue)}
67
      themeVariant="dark"
68
      style={{ height: 216 }}
69
    >
70
      <PickerIOS.Item label="First Option" value="option1" />
71
      <PickerIOS.Item label="Second Option" value="option2" />
72
      <PickerIOS.Item label="Third Option" value="option3" />
73
    </PickerIOS>
74
  );
75
}
76

77
// iOS picker with custom item styling
78
function StyledIOSPicker() {
79
  const [selectedSize, setSelectedSize] = useState("medium");
80
  
81
  return (
82
    <PickerIOS
83
      selectedValue={selectedSize}
84
      onValueChange={setSelectedSize}
85
      itemStyle={{
86
        fontSize: 18,
87
        color: '#007AFF',
88
        fontWeight: '500'
89
      }}
90
      numberOfLines={2}
91
    >
92
      <PickerIOS.Item label="Small" value="small" color="#FF6B6B" />
93
      <PickerIOS.Item label="Medium" value="medium" color="#4ECDC4" />
94
      <PickerIOS.Item label="Large" value="large" color="#45B7D1" />
95
    </PickerIOS>
96
  );
97
}
98

99
// iOS picker with change event handling
100
function EventHandlingIOSPicker() {
101
  const [selectedCategory, setSelectedCategory] = useState("electronics");
102
  
103
  const handleChange = (event) => {
104
    console.log('Change event:', event.nativeEvent);
105
    setSelectedCategory(event.nativeEvent.itemValue);
106
  };
107
  
108
  const handleValueChange = (itemValue, itemIndex) => {
109
    console.log('Value changed:', itemValue, 'at index:', itemIndex);
110
    setSelectedCategory(itemValue);
111
  };
112
  
113
  return (
114
    <PickerIOS
115
      selectedValue={selectedCategory}
116
      onChange={handleChange}
117
      onValueChange={handleValueChange}
118
      testID="category-picker"
119
    >
120
      <PickerIOS.Item 
121
        label="Electronics" 
122
        value="electronics" 
123
        testID="electronics-item" 
124
      />
125
      <PickerIOS.Item 
126
        label="Clothing" 
127
        value="clothing" 
128
        testID="clothing-item" 
129
      />
130
      <PickerIOS.Item 
131
        label="Books" 
132
        value="books" 
133
        testID="books-item" 
134
      />
135
    </PickerIOS>
136
  );
137
}
138
```
139

140
### iOS-Specific Props
141

142
Properties that are unique to the iOS picker implementation.
143

144
```typescript { .api }
145
/**
146
 * Style to apply to each individual item label
147
 * Accepts standard React Native text style properties
148
 */
149
itemStyle?: StyleProp<TextStyle>;
150

151
/**
152
 * iOS theme variant for automatic styling
153
 * Accepts 'light' or 'dark' for system appearance matching
154
 */
155
themeVariant?: string;
156

157
/**
158
 * Maximum number of lines for item text before truncation
159
 * Defaults to 1, increases height if set higher
160
 */
161
numberOfLines?: number;
162

163
/**
164
 * Native iOS change event providing detailed event information
165
 * Includes both itemValue and itemIndex in nativeEvent
166
 */
167
onChange?: React.SyntheticEvent<{
168
  itemValue: ItemValue, 
169
  itemIndex: number
170
}>;
171
```
172

173
### PickerIOS Item Component
174

175
iOS-specific item component with enhanced color support.
176

177
```typescript { .api }
178
/**
179
 * Individual item within PickerIOS component
180
 * Supports iOS-specific styling and color options
181
 */
182
interface PickerIOSItemProps {
183
  /** Display text shown in the picker */
184
  label?: string;
185
  /** Value associated with this item */
186
  value?: number | string;
187
  /** Text color for this specific item */
188
  color?: string;
189
  /** Testing identifier for this item */
190
  testID?: string;
191
}
192

193
declare class PickerIOSItem extends React.Component<PickerIOSItemProps, {}> {}
194
```
195

196
### Native iOS Integration
197

198
The PickerIOS component integrates directly with iOS native picker controls for optimal performance and native appearance.
199

200
**Key iOS Features:**
201
- Native iOS wheel picker appearance
202
- Automatic theme variant support (light/dark mode)
203
- High-performance native scrolling
204
- iOS-standard selection indicators
205
- Haptic feedback integration
206
- Accessibility support with VoiceOver
207

208
**Performance Characteristics:**
209
- Direct native component rendering
210
- Optimized for large item lists
211
- Native memory management
212
- Smooth 60fps scrolling performance
213

214
**iOS Styling Guidelines:**
215
- Follows iOS Human Interface Guidelines
216
- Automatic system font integration
217
- Respects user accessibility settings
218
- Native color scheme support