0
# Event System
1

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

4
## Capabilities
5

6
### DateTimePickerEvent
7

8
Main event object passed to onChange handlers containing event type and native event data.
9

10
```typescript { .api }
11
/**
12
 * Event object passed to onChange handlers
13
 */
14
type DateTimePickerEvent = {
15
  /** Type of event that occurred */
16
  type: EvtTypes;
17
  /** Native event data with timestamp and timezone information */
18
  nativeEvent: {
19
    /** Unix timestamp in milliseconds */
20
    timestamp: number;
21
    /** Timezone offset in minutes from UTC */
22
    utcOffset: number;
23
  };
24
};
25
```
26

27
### Event Types
28

29
Enumeration of possible event types from picker interactions.
30

31
```typescript { .api }
32
/**
33
 * Possible event types from date/time picker interactions
34
 */
35
type EvtTypes = 'set' | 'neutralButtonPressed' | 'dismissed';
36
```
37

38
**Event Type Descriptions:**
39
- `'set'` - User selected a date/time and confirmed (positive button pressed)
40
- `'dismissed'` - Dialog was dismissed without selection (negative button, back button, or tap outside)
41
- `'neutralButtonPressed'` - Neutral button was pressed (typically "Clear" button on Android)
42

43
### Event Creator Functions
44

45
Utility functions for creating standardized event parameters. These are primarily used internally but are exported for custom event handling.
46

47
```typescript { .api }
48
/**
49
 * Creates event parameters for date/time set events
50
 * @param date - The selected date
51
 * @param utcOffset - Timezone offset in minutes from UTC
52
 * @returns Tuple of [event, date] for onChange handler
53
 */
54
function createDateTimeSetEvtParams(
55
  date: Date,
56
  utcOffset: number
57
): [DateTimePickerEvent, Date];
58

59
/**
60
 * Creates event parameters for dismiss events
61
 * @param date - The original date value
62
 * @param utcOffset - Timezone offset in minutes from UTC
63
 * @returns Tuple of [event, date] for onChange handler
64
 */
65
function createDismissEvtParams(
66
  date: Date,
67
  utcOffset: number
68
): [DateTimePickerEvent, Date];
69

70
/**
71
 * Creates event parameters for neutral button events
72
 * @param date - The original date value
73
 * @param utcOffset - Timezone offset in minutes from UTC
74
 * @returns Tuple of [event, date] for onChange handler
75
 */
76
function createNeutralEvtParams(
77
  date: Date,
78
  utcOffset: number
79
): [DateTimePickerEvent, Date];
80
```
81

82
**Usage Examples:**
83

84
```typescript
85
import {
86
  createDateTimeSetEvtParams,
87
  createDismissEvtParams,
88
  createNeutralEvtParams
89
} from "@react-native-community/datetimepicker";
90

91
// Creating custom events (typically for testing or advanced use cases)
92
const selectedDate = new Date('2023-12-25');
93
const timezoneOffset = -480; // PST offset in minutes
94

95
// Create a "set" event
96
const [setEvent, setDate] = createDateTimeSetEvtParams(selectedDate, timezoneOffset);
97
console.log(setEvent.type); // 'set'
98
console.log(setEvent.nativeEvent.timestamp); // 1703462400000
99
console.log(setEvent.nativeEvent.utcOffset); // -480
100

101
// Create a "dismissed" event
102
const [dismissEvent, dismissDate] = createDismissEvtParams(selectedDate, timezoneOffset);
103
console.log(dismissEvent.type); // 'dismissed'
104

105
// Create a "neutral button" event
106
const [neutralEvent, neutralDate] = createNeutralEvtParams(selectedDate, timezoneOffset);
107
console.log(neutralEvent.type); // 'neutralButtonPressed'
108
```
109

110
### onChange Handler Pattern
111

112
The onChange callback follows a consistent pattern across all platforms and usage modes.
113

114
```typescript { .api }
115
/**
116
 * Standard onChange handler signature
117
 * @param event - Event object with type and native event data
118
 * @param date - Selected date (undefined for dismiss events)
119
 */
120
type OnChangeHandler = (event: DateTimePickerEvent, date?: Date) => void;
121
```
122

123
**Complete onChange Implementation:**
124

125
```typescript
126
import React, { useState } from "react";
127
import DateTimePicker from "@react-native-community/datetimepicker";
128

129
function DatePickerWithEventHandling() {
130
  const [date, setDate] = useState(new Date());
131
  const [lastEventInfo, setLastEventInfo] = useState(null);
132

133
  const handleDateChange = (event: DateTimePickerEvent, selectedDate?: Date) => {
134
    // Log event details
135
    console.log('Event type:', event.type);
136
    console.log('Timestamp:', event.nativeEvent.timestamp);
137
    console.log('UTC Offset:', event.nativeEvent.utcOffset);
138
    console.log('Selected date:', selectedDate);
139

140
    // Store event info for display
141
    setLastEventInfo({
142
      type: event.type,
143
      timestamp: new Date(event.nativeEvent.timestamp),
144
      utcOffset: event.nativeEvent.utcOffset,
145
      selectedDate: selectedDate
146
    });
147

148
    // Handle different event types
149
    switch (event.type) {
150
      case 'set':
151
        if (selectedDate) {
152
          setDate(selectedDate);
153
          console.log('Date updated to:', selectedDate.toISOString());
154
        }
155
        break;
156

157
      case 'dismissed':
158
        console.log('Picker dismissed without selection');
159
        // Optionally hide picker or show message
160
        break;
161

162
      case 'neutralButtonPressed':
163
        console.log('Clear/neutral button pressed');
164
        // Optionally clear the date or show default
165
        setDate(new Date()); // Reset to today
166
        break;
167
    }
168
  };
169

170
  return (
171
    <DateTimePicker
172
      value={date}
173
      mode="date"
174
      display="default"
175
      onChange={handleDateChange}
176
    />
177
  );
178
}
179
```
180

181
### Timezone Handling
182

183
The event system provides timezone information in the `utcOffset` field.
184

185
```typescript
186
const handleDateChange = (event: DateTimePickerEvent, selectedDate?: Date) => {
187
  const { timestamp, utcOffset } = event.nativeEvent;
188
  
189
  // Convert timestamp to Date object
190
  const eventDate = new Date(timestamp);
191
  
192
  // Calculate timezone information
193
  const offsetHours = Math.abs(utcOffset) / 60;
194
  const offsetDirection = utcOffset < 0 ? '-' : '+';
195
  const timezoneString = `UTC${offsetDirection}${offsetHours}`;
196
  
197
  console.log(`Event occurred at ${eventDate.toISOString()} (${timezoneString})`);
198
  
199
  // Handle timezone-aware date processing
200
  if (selectedDate) {
201
    // The selectedDate is already in the local timezone
202
    console.log('Local time:', selectedDate.toLocaleString());
203
    console.log('UTC time:', selectedDate.toISOString());
204
  }
205
};
206
```
207

208
### Error Event Handling (Android Only)
209

210
Android implementations support an additional `onError` callback for handling native errors.
211

212
```typescript { .api }
213
/**
214
 * Error handler for Android native errors
215
 * @param error - Error object from native Android code
216
 */
217
type OnErrorHandler = (error: Error) => void;
218
```
219

220
**Usage Example:**
221

222
```typescript
223
import { DateTimePickerAndroid } from "@react-native-community/datetimepicker";
224

225
DateTimePickerAndroid.open({
226
  value: new Date(),
227
  onChange: (event, date) => {
228
    // Handle normal events
229
  },
230
  onError: (error) => {
231
    console.error('Native Android error:', error.message);
232
    
233
    // Common error scenarios:
234
    switch (error.message) {
235
      case 'Activity is null':
236
        console.log('App is in background or activity destroyed');
237
        break;
238
      case 'Dialog already showing':
239
        console.log('Another picker dialog is already open');
240
        break;
241
      default:
242
        console.log('Unexpected error:', error);
243
    }
244
  },
245
});
246
```
247

248
### Platform-Specific Event Behavior
249

250
Different platforms may have slightly different event patterns:
251

252
**iOS:**
253
- Events fire immediately when user interacts with the picker
254
- `dismissed` events are less common (typically only on modal dismissal)
255
- Continuous updates during scrolling in spinner mode
256

257
**Android:**
258
- Events fire when dialog is dismissed (either confirmed or cancelled)
259
- Always includes `dismissed` event when cancelled
260
- `neutralButtonPressed` available for custom neutral buttons (not in Material 3)
261

262
**Windows:**
263
- Events similar to iOS with immediate feedback
264
- Limited event types (primarily `set` and `dismissed`)
265

266
```typescript
267
import { Platform } from 'react-native';
268

269
const handleDateChange = (event: DateTimePickerEvent, selectedDate?: Date) => {
270
  if (Platform.OS === 'ios') {
271
    // iOS may fire multiple events during interaction
272
    if (event.type === 'set') {
273
      // Update UI immediately
274
      setDate(selectedDate);
275
    }
276
  } else if (Platform.OS === 'android') {
277
    // Android fires single event when dialog closes
278
    switch (event.type) {
279
      case 'set':
280
        setDate(selectedDate);
281
        hideAndroidPicker();
282
        break;
283
      case 'dismissed':
284
        hideAndroidPicker();
285
        break;
286
    }
287
  }
288
};
289
```