0
# Android Imperative API
1

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

4
## Capabilities
5

6
### DateTimePickerAndroid
7

8
Imperative API for showing native Android date/time picker dialogs. This is the recommended approach for Android as it better models the native dialog behavior.
9

10
```typescript { .api }
11
declare namespace DateTimePickerAndroidType {
12
  const open: (args: AndroidNativeProps) => void;
13
  const dismiss: (mode: AndroidNativeProps['mode'], design?: AndroidNativeProps['design']) => Promise<boolean>;
14
}
15

16
declare const DateTimePickerAndroid: typeof DateTimePickerAndroidType;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { DateTimePickerAndroid } from "@react-native-community/datetimepicker";
23

24
// Basic date picker
25
function showDatePicker() {
26
  DateTimePickerAndroid.open({
27
    value: new Date(),
28
    onChange: (event, date) => {
29
      if (event.type === 'set' && date) {
30
        console.log('Selected date:', date);
31
      }
32
    },
33
    mode: 'date',
34
    display: 'default',
35
  });
36
}
37

38
// Material Design 3 date picker with custom styling
39
function showMaterialDatePicker() {
40
  DateTimePickerAndroid.open({
41
    value: new Date(),
42
    onChange: (event, date) => {
43
      switch (event.type) {
44
        case 'set':
45
          console.log('Date selected:', date);
46
          break;
47
        case 'dismissed':
48
          console.log('Dialog dismissed');
49
          break;
50
        case 'neutralButtonPressed':
51
          console.log('Clear button pressed');
52
          break;
53
      }
54
    },
55
    mode: 'date',
56
    design: 'material',
57
    title: 'Select your birthday',
58
    fullscreen: false,
59
    initialInputMode: 'calendar',
60
    positiveButton: { label: 'OK', textColor: '#2196F3' },
61
    negativeButton: { label: 'Cancel', textColor: '#757575' },
62
    neutralButton: { label: 'Clear', textColor: '#FF5722' },
63
  });
64
}
65

66
// Time picker with constraints
67
function showTimePicker() {
68
  DateTimePickerAndroid.open({
69
    value: new Date(),
70
    onChange: (event, date) => {
71
      if (event.type === 'set' && date) {
72
        console.log('Selected time:', date.toTimeString());
73
      }
74
    },
75
    mode: 'time',
76
    is24Hour: true,
77
    minuteInterval: 15,
78
    onError: (error) => {
79
      console.error('Picker error:', error);
80
    },
81
  });
82
}
83
```
84

85
### Open Method
86

87
Shows a native Android date/time picker dialog.
88

89
```typescript { .api }
90
/**
91
 * Opens native Android date/time picker dialog
92
 * @param args - Configuration object with picker options
93
 * @returns void - Results are provided via onChange callback
94
 */
95
open: (args: AndroidNativeProps) => void;
96
```
97

98
The `open` method accepts all the same properties as the Android component props, including:
99

100
- **Required Properties:**
101
  - `value: Date` - The initially selected date/time
102
  - `onChange: (event, date) => void` - Callback for handling results
103

104
- **Mode and Display:**
105
  - `mode?: 'date' | 'time'` - Type of picker to show
106
  - `display?: 'spinner' | 'default' | 'clock' | 'calendar'` - Visual style (not supported in Material 3)
107
  - `design?: 'default' | 'material'` - Use Material 3 or default Android pickers
108

109
- **Material 3 Options:**
110
  - `title?: string` - Dialog title
111
  - `fullscreen?: boolean` - Show as fullscreen dialog
112
  - `initialInputMode?: 'default' | 'keyboard'` - Initial input method
113

114
- **Button Configuration:**
115
  - `positiveButton?: {label?: string, textColor?: ColorValue}` - OK button
116
  - `negativeButton?: {label?: string, textColor?: ColorValue}` - Cancel button
117
  - `neutralButton?: {label?: string, textColor?: ColorValue}` - Clear button (not in Material 3)
118

119
- **Constraints:**
120
  - `minimumDate?: Date` - Earliest selectable date
121
  - `maximumDate?: Date` - Latest selectable date
122
  - `minuteInterval?: MinuteInterval` - Minute step interval (not in Material 3)
123
  - `is24Hour?: boolean` - Use 24-hour time format
124
  - `firstDayOfWeek?: DAY_OF_WEEK` - Starting day of week for calendar
125

126
- **Timezone Support:**
127
  - `timeZoneOffsetInMinutes?: number` - Force specific timezone offset
128
  - `timeZoneName?: string` - IANA timezone database name
129

130
- **Error Handling:**
131
  - `onError?: (error: Error) => void` - Callback for native errors
132

133
### Dismiss Method
134

135
Programmatically dismisses the currently shown picker dialog.
136

137
```typescript { .api }
138
/**
139
 * Dismisses currently shown picker dialog
140
 * @param mode - The mode of picker to dismiss ('date' or 'time')
141
 * @param design - Optional design type ('default' or 'material') to specify which picker to dismiss
142
 * @returns Promise<boolean> - true if dialog was dismissed, false if none was showing
143
 */
144
dismiss: (mode: AndroidNativeProps['mode'], design?: AndroidNativeProps['design']) => Promise<boolean>;
145
```
146

147
**Usage Examples:**
148

149
```javascript
150
// Dismiss date picker
151
const dismissed = await DateTimePickerAndroid.dismiss('date');
152
if (dismissed) {
153
  console.log('Date picker was dismissed');
154
} else {
155
  console.log('No date picker was showing');
156
}
157

158
// Dismiss time picker
159
await DateTimePickerAndroid.dismiss('time');
160
```
161

162
### Event Handling
163

164
The `onChange` callback receives detailed event information:
165

166
```typescript { .api }
167
type AndroidPickerChangeHandler = (
168
  event: DateTimePickerEvent,
169
  date?: Date
170
) => void;
171

172
type DateTimePickerEvent = {
173
  type: 'set' | 'dismissed' | 'neutralButtonPressed';
174
  nativeEvent: {
175
    timestamp: number;
176
    utcOffset: number;
177
  };
178
};
179
```
180

181
**Event Types:**
182
- `'set'` - User selected a date/time (positive button pressed)
183
- `'dismissed'` - Dialog was dismissed without selection (negative button or back button)
184
- `'neutralButtonPressed'` - Neutral button was pressed (typically "Clear" - not available in Material 3)
185

186
### Material Design 3 Features
187

188
When using `design: 'material'`, additional features are available:
189

190
```typescript
191
// Material 3 specific properties
192
{
193
  design: 'material',
194
  title: 'Select Date',           // Custom dialog title
195
  fullscreen: false,              // Control fullscreen mode
196
  initialInputMode: 'calendar',   // Start with calendar or keyboard input
197
  // Note: neutralButton, minuteInterval, and display are not supported
198
}
199
```
200

201
### Error Handling
202

203
The `onError` callback handles native Android errors:
204

205
```typescript
206
DateTimePickerAndroid.open({
207
  value: new Date(),
208
  onChange: (event, date) => { /* handle success */ },
209
  onError: (error) => {
210
    console.error('Android picker error:', error.message);
211
    // Common errors:
212
    // - Activity is null
213
    // - Dialog already showing
214
    // - Invalid date range
215
  },
216
});
217
```
218

219
### Platform Compatibility
220

221
The DateTimePickerAndroid API is only available on Android. On other platforms, the methods will log warnings and do nothing:
222

223
```typescript
224
// Safe cross-platform usage
225
import { Platform } from 'react-native';
226
import { DateTimePickerAndroid } from '@react-native-community/datetimepicker';
227

228
if (Platform.OS === 'android') {
229
  DateTimePickerAndroid.open({
230
    value: new Date(),
231
    onChange: handleChange,
232
    mode: 'date',
233
  });
234
}
235
```