0
# React Native DateTimePicker
1

2
React Native DateTimePicker provides cross-platform date and time picker components with native iOS, Android, and Windows implementations. It offers both declarative React components and imperative APIs, with comprehensive customization options including Material Design 3 support, timezone handling, and accessibility features.
3

4
## Package Information
5

6
- **Package Name**: @react-native-community/datetimepicker
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install @react-native-community/datetimepicker`
10

11
## Core Imports
12

13
```typescript
14
import DateTimePicker, { 
15
  DateTimePickerAndroid,
16
  DateTimePickerEvent,
17
  EvtTypes,
18
  Event,
19
  ButtonType,
20
  IOSNativeProps,
21
  AndroidNativeProps,
22
  WindowsNativeProps,
23
  DatePickerOptions,
24
  TimePickerOptions,
25
  RCTDateTimePickerNative,
26
  NativeRef,
27
  createDateTimeSetEvtParams,
28
  createDismissEvtParams,
29
  createNeutralEvtParams
30
} from "@react-native-community/datetimepicker";
31
```
32

33
For CommonJS:
34

35
```javascript
36
const DateTimePicker = require("@react-native-community/datetimepicker").default;
37
const { DateTimePickerAndroid } = require("@react-native-community/datetimepicker");
38
```
39

40
## Basic Usage
41

42
```typescript
43
import React, { useState } from "react";
44
import { View, Button } from "react-native";
45
import DateTimePicker from "@react-native-community/datetimepicker";
46

47
function DatePickerExample() {
48
  const [date, setDate] = useState(new Date());
49
  const [show, setShow] = useState(false);
50

51
  const onChange = (event, selectedDate) => {
52
    setShow(false);
53
    if (selectedDate) {
54
      setDate(selectedDate);
55
    }
56
  };
57

58
  return (
59
    <View>
60
      <Button title="Show Date Picker" onPress={() => setShow(true)} />
61
      {show && (
62
        <DateTimePicker
63
          value={date}
64
          mode="date"
65
          display="default"
66
          onChange={onChange}
67
        />
68
      )}
69
    </View>
70
  );
71
}
72
```
73

74
## Architecture
75

76
React Native DateTimePicker is built around platform-specific implementations:
77

78
- **iOS Integration**: Uses native `UIDatePicker` with support for various display modes (compact, inline, spinner)
79
- **Android Integration**: Uses native `DatePickerDialog` and `TimePickerDialog` with Material Design 3 support
80
- **Windows Integration**: Uses native `CalendarDatePicker` and `TimePicker` components
81
- **Cross-Platform API**: Unified TypeScript interfaces that adapt to platform capabilities
82
- **Event System**: Comprehensive event handling for user interactions, dismissals, and errors
83

84
The package provides two usage patterns:
85
1. **Declarative Component**: Standard React component approach (recommended for iOS)
86
2. **Imperative API**: Programmatic dialog control via `DateTimePickerAndroid` (recommended for Android)
87

88
## Capabilities
89

90
### Core DateTimePicker Component
91

92
Cross-platform React component providing native date and time selection with platform-specific display modes and comprehensive customization options.
93

94
```typescript { .api }
95
declare const DateTimePicker: React.FC<
96
  IOSNativeProps | AndroidNativeProps | WindowsNativeProps
97
>;
98

99
type IOSNativeProps = Readonly<{
100
  value: Date;
101
  onChange?: (event: DateTimePickerEvent, date?: Date) => void;
102
  mode?: IOSMode;
103
  display?: IOSDisplay;
104
  locale?: string;
105
  minuteInterval?: MinuteInterval;
106
  timeZoneOffsetInMinutes?: number;
107
  timeZoneName?: string;
108
  textColor?: string;
109
  accentColor?: string;
110
  themeVariant?: 'dark' | 'light';
111
  disabled?: boolean;
112
  maximumDate?: Date;
113
  minimumDate?: Date;
114
}>;
115

116
type AndroidNativeProps = Readonly<{
117
  value: Date;
118
  onChange?: (event: DateTimePickerEvent, date?: Date) => void;
119
  mode?: AndroidMode;
120
  display?: Display;
121
  design?: Design;
122
  initialInputMode?: InputMode;
123
  title?: string;
124
  fullscreen?: boolean;
125
  is24Hour?: boolean;
126
  minuteInterval?: MinuteInterval;
127
  timeZoneOffsetInMinutes?: number;
128
  timeZoneName?: string;
129
  maximumDate?: Date;
130
  minimumDate?: Date;
131
  positiveButton?: ButtonType;
132
  neutralButton?: ButtonType;
133
  negativeButton?: ButtonType;
134
  firstDayOfWeek?: DAY_OF_WEEK;
135
  onError?: (error: Error) => void;
136
}>;
137

138
type WindowsNativeProps = Readonly<{
139
  value: Date;
140
  onChange?: (event: DateTimePickerEvent, date?: Date) => void;
141
  display?: Display;
142
  placeholderText?: string;
143
  dateFormat?: WindowsDateFormat;
144
  dayOfWeekFormat?: WindowsDayOfWeekFormat;
145
  firstDayOfWeek?: DAY_OF_WEEK;
146
  timeZoneOffsetInSeconds?: number;
147
  is24Hour?: boolean;
148
  minuteInterval?: number;
149
  accessibilityLabel?: string;
150
  maximumDate?: Date;
151
  minimumDate?: Date;
152
  timeZoneName?: string;
153
}>;
154
```
155

156
[Component API](./component-api.md)
157

158
### Android Imperative API
159

160
Native Android dialog API for showing date and time pickers programmatically, providing fine-grained control over dialog behavior and Material Design 3 styling.
161

162
```typescript { .api }
163
interface DateTimePickerAndroidType {
164
  open: (args: AndroidNativeProps) => void;
165
  dismiss: (mode: AndroidNativeProps['mode']) => Promise<boolean>;
166
}
167

168
declare const DateTimePickerAndroid: DateTimePickerAndroidType;
169
```
170

171
[Android Imperative API](./android-imperative-api.md)
172

173
### Event System
174

175
Comprehensive event handling system providing detailed information about user interactions, including timestamps, timezone offsets, and event types.
176

177
```typescript { .api }
178
type DateTimePickerEvent = {
179
  type: EvtTypes;
180
  nativeEvent: {
181
    timestamp: number;
182
    utcOffset: number;
183
  };
184
};
185

186
type EvtTypes = 'set' | 'neutralButtonPressed' | 'dismissed';
187

188
function createDateTimeSetEvtParams(
189
  date: Date,
190
  utcOffset: number
191
): [DateTimePickerEvent, Date];
192

193
function createDismissEvtParams(
194
  date: Date,
195
  utcOffset: number
196
): [DateTimePickerEvent, Date];
197

198
function createNeutralEvtParams(
199
  date: Date,
200
  utcOffset: number
201
): [DateTimePickerEvent, Date];
202
```
203

204
[Event System](./event-system.md)
205

206
### Event Creator Functions
207

208
Utility functions for creating standardized event parameters, primarily used internally but exported for custom event handling scenarios.
209

210
```typescript { .api }
211
function createDateTimeSetEvtParams(
212
  date: Date,
213
  utcOffset: number
214
): [DateTimePickerEvent, Date];
215

216
function createDismissEvtParams(
217
  date: Date,
218
  utcOffset: number
219
): [DateTimePickerEvent, Date];
220

221
function createNeutralEvtParams(
222
  date: Date,
223
  utcOffset: number
224
): [DateTimePickerEvent, Date];
225
```
226

227
## Core Types
228

229
```typescript { .api }
230
import { FC, Ref, SyntheticEvent } from 'react';
231
import { ColorValue, NativeMethods, ViewProps } from 'react-native';
232

233
type IOSMode = 'date' | 'time' | 'datetime' | 'countdown';
234
type AndroidMode = 'date' | 'time';
235
type Display = 'spinner' | 'default' | 'clock' | 'calendar';
236
type IOSDisplay = 'default' | 'compact' | 'inline' | 'spinner';
237
type MinuteInterval = 1 | 2 | 3 | 4 | 5 | 6 | 10 | 12 | 15 | 20 | 30;
238
type Design = 'default' | 'material';
239
type InputMode = 'default' | 'keyboard';
240
type DAY_OF_WEEK = 0 | 1 | 2 | 3 | 4 | 5 | 6;
241

242
type WindowsDateFormat = 
243
  | 'day month year'
244
  | 'dayofweek day month'
245
  | 'longdate'
246
  | 'shortdate';
247

248
type WindowsDayOfWeekFormat = 
249
  | '{dayofweek.abbreviated(2)}'
250
  | '{dayofweek.abbreviated(3)}'
251
  | '{dayofweek.full}';
252

253
type ButtonType = {
254
  label?: string;
255
  textColor?: ColorValue;
256
};
257

258
type Event = SyntheticEvent<Readonly<{timestamp: number}>>;
259

260
type BaseOptions = {
261
  value: Date;
262
  onChange?: (event: DateTimePickerEvent, date?: Date) => void;
263
};
264

265
type DateOptions = BaseOptions & {
266
  maximumDate?: Date;
267
  minimumDate?: Date;
268
};
269

270
type TimeOptions = BaseOptions & {
271
  is24Hour?: boolean;
272
};
273

274
type DatePickerOptions = DateOptions & {
275
  display?: Display;
276
};
277

278
type TimePickerOptions = TimeOptions & {
279
  display?: Display;
280
};
281

282
type RCTDateTimePickerNative = NativeMethods;
283
type NativeRef = {
284
  current: Ref<RCTDateTimePickerNative> | null;
285
};
286
```