0
# Component API
1
2
Cross-platform React component providing native date and time selection with platform-specific display modes and comprehensive customization options.
3
4
## Capabilities
5
6
### DateTimePicker Component
7
8
Main React component for date/time picking with platform-specific implementations.
9
10
```typescript { .api }
11
/**
12
* Cross-platform DateTimePicker component
13
* @param props - Platform-specific props (IOSNativeProps | AndroidNativeProps | WindowsNativeProps)
14
* @returns React component for date/time selection
15
*/
16
declare const DateTimePicker: React.FC<
17
IOSNativeProps | AndroidNativeProps | WindowsNativeProps
18
>;
19
```
20
21
**Usage Examples:**
22
23
```typescript
24
import React, { useState } from "react";
25
import DateTimePicker from "@react-native-community/datetimepicker";
26
27
// iOS Usage - Declarative component
28
function IOSDatePicker() {
29
const [date, setDate] = useState(new Date());
30
31
return (
32
<DateTimePicker
33
value={date}
34
mode="date"
35
display="compact"
36
onChange={(event, selectedDate) => setDate(selectedDate || date)}
37
locale="en-US"
38
textColor="#007AFF"
39
accentColor="#FF6B6B"
40
themeVariant="light"
41
/>
42
);
43
}
44
45
// Android Usage - Component with Material Design
46
function AndroidDatePicker() {
47
const [date, setDate] = useState(new Date());
48
const [show, setShow] = useState(false);
49
50
return (
51
<>
52
<Button title="Show Picker" onPress={() => setShow(true)} />
53
{show && (
54
<DateTimePicker
55
value={date}
56
mode="date"
57
display="default"
58
design="material"
59
title="Select Date"
60
fullscreen={false}
61
onChange={(event, selectedDate) => {
62
setShow(false);
63
if (selectedDate) setDate(selectedDate);
64
}}
65
/>
66
)}
67
</>
68
);
69
}
70
```
71
72
### iOS Native Props
73
74
Properties specific to iOS implementation using UIDatePicker.
75
76
```typescript { .api }
77
type IOSNativeProps = Readonly<{
78
/** The currently selected date (required) */
79
value: Date;
80
81
/** Date change handler - called when user changes date/time */
82
onChange?: (event: DateTimePickerEvent, date?: Date) => void;
83
84
/** The date picker mode */
85
mode?: IOSMode;
86
87
/** Sets the preferredDatePickerStyle for picker */
88
display?: IOSDisplay;
89
90
/** The date picker locale */
91
locale?: string;
92
93
/** The interval at which minutes can be selected */
94
minuteInterval?: MinuteInterval;
95
96
/** Timezone offset in minutes */
97
timeZoneOffsetInMinutes?: number;
98
99
/** The tz database name */
100
timeZoneName?: string;
101
102
/** The date picker text color */
103
textColor?: string;
104
105
/** The date picker accent color (selected date and navigation icons) */
106
accentColor?: string;
107
108
/** Override theme variant used by iOS native picker */
109
themeVariant?: 'dark' | 'light';
110
111
/** Is this picker disabled? */
112
disabled?: boolean;
113
114
/** Maximum date - restricts the range of possible values */
115
maximumDate?: Date;
116
117
/** Minimum date - restricts the range of possible values */
118
minimumDate?: Date;
119
}>;
120
```
121
122
### Android Native Props
123
124
Properties specific to Android implementation using DatePickerDialog and TimePickerDialog.
125
126
```typescript { .api }
127
type AndroidNativeProps = Readonly<{
128
/** The currently selected date (required) */
129
value: Date;
130
131
/** Date change handler - called when user changes date/time or dismisses */
132
onChange?: (event: DateTimePickerEvent, date?: Date) => void;
133
134
/** The date picker mode */
135
mode?: AndroidMode;
136
137
/** The display options (not supported for Material 3 pickers) */
138
display?: Display;
139
140
/** Use Material 3 pickers or the default ones */
141
design?: Design;
142
143
/** (Material 3 only) The initial input mode when the dialog opens */
144
initialInputMode?: InputMode;
145
146
/** (Material 3 only) The title of the dialog */
147
title?: string;
148
149
/** (Material 3 only) Controls if the date picker should be shown as fullscreen dialog */
150
fullscreen?: boolean;
151
152
/** Display TimePicker in 24 hour */
153
is24Hour?: boolean;
154
155
/** The interval at which minutes can be selected (not supported in Material 3) */
156
minuteInterval?: MinuteInterval;
157
158
/** Timezone offset in minutes */
159
timeZoneOffsetInMinutes?: number;
160
161
/** The tz database name */
162
timeZoneName?: string;
163
164
/** Maximum date - restricts the range of possible values */
165
maximumDate?: Date;
166
167
/** Minimum date - restricts the range of possible values */
168
minimumDate?: Date;
169
170
/** Positive button configuration */
171
positiveButton?: ButtonType;
172
173
/** Neutral button configuration (not supported in Material 3) */
174
neutralButton?: ButtonType;
175
176
/** Negative button configuration */
177
negativeButton?: ButtonType;
178
179
/** @deprecated use positiveButton instead */
180
positiveButtonLabel?: string;
181
182
/** @deprecated use neutralButton instead */
183
neutralButtonLabel?: string;
184
185
/** @deprecated use negativeButton instead */
186
negativeButtonLabel?: string;
187
188
/** Sets the first day of the week shown in the calendar */
189
firstDayOfWeek?: DAY_OF_WEEK;
190
191
/** Callback when an error occurs inside the date picker native code */
192
onError?: (error: Error) => void;
193
}>;
194
```
195
196
### Windows Native Props
197
198
Properties specific to Windows implementation using CalendarDatePicker and TimePicker.
199
200
```typescript { .api }
201
type WindowsNativeProps = Readonly<{
202
/** The currently selected date (required) */
203
value: Date;
204
205
/** Date change handler - called when user changes date/time */
206
onChange?: (event: DateTimePickerEvent, date?: Date) => void;
207
208
/** The display options */
209
display?: Display;
210
211
/** Placeholder text for the picker */
212
placeholderText?: string;
213
214
/** Date format style */
215
dateFormat?: WindowsDateFormat;
216
217
/** Day of week format style */
218
dayOfWeekFormat?: WindowsDayOfWeekFormat;
219
220
/** Sets the first day of the week shown in the calendar */
221
firstDayOfWeek?: DAY_OF_WEEK;
222
223
/** Timezone offset in seconds */
224
timeZoneOffsetInSeconds?: number;
225
226
/** The tz database name */
227
timeZoneName?: string;
228
229
/** Display TimePicker in 24 hour */
230
is24Hour?: boolean;
231
232
/** The interval at which minutes can be selected */
233
minuteInterval?: number;
234
235
/** Accessibility label for the picker */
236
accessibilityLabel?: string;
237
238
/** Maximum date - restricts the range of possible values */
239
maximumDate?: Date;
240
241
/** Minimum date - restricts the range of possible values */
242
minimumDate?: Date;
243
}>;
244
```
245
246
### Mode and Display Types
247
248
Platform-specific modes and display options.
249
250
```typescript { .api }
251
/** iOS picker modes */
252
type IOSMode = 'date' | 'time' | 'datetime' | 'countdown';
253
254
/** Android picker modes */
255
type AndroidMode = 'date' | 'time';
256
257
/** Android display styles */
258
type Display = 'spinner' | 'default' | 'clock' | 'calendar';
259
260
/** iOS display styles */
261
type IOSDisplay = 'default' | 'compact' | 'inline' | 'spinner';
262
263
/** Material Design system selection */
264
type Design = 'default' | 'material';
265
266
/** Android Material 3 input mode */
267
type InputMode = 'default' | 'keyboard';
268
269
/** Minute selection intervals */
270
type MinuteInterval = 1 | 2 | 3 | 4 | 5 | 6 | 10 | 12 | 15 | 20 | 30;
271
272
/** Day of week values (0=Sunday, 6=Saturday) */
273
type DAY_OF_WEEK = 0 | 1 | 2 | 3 | 4 | 5 | 6;
274
275
/** Windows date format options */
276
type WindowsDateFormat =
277
| 'day month year'
278
| 'dayofweek day month'
279
| 'longdate'
280
| 'shortdate';
281
282
/** Windows day of week format options */
283
type WindowsDayOfWeekFormat =
284
| '{dayofweek.abbreviated(2)}'
285
| '{dayofweek.abbreviated(3)}'
286
| '{dayofweek.full}';
287
```