Cross-platform React Native date and time picker component with native iOS, Android, and Windows implementations.
—
Comprehensive event handling system providing detailed information about user interactions, including timestamps, timezone offsets, and event types.
Main event object passed to onChange handlers containing event type and native event data.
/**
* Event object passed to onChange handlers
*/
type DateTimePickerEvent = {
/** Type of event that occurred */
type: EvtTypes;
/** Native event data with timestamp and timezone information */
nativeEvent: {
/** Unix timestamp in milliseconds */
timestamp: number;
/** Timezone offset in minutes from UTC */
utcOffset: number;
};
};Enumeration of possible event types from picker interactions.
/**
* Possible event types from date/time picker interactions
*/
type EvtTypes = 'set' | 'neutralButtonPressed' | 'dismissed';Event Type Descriptions:
'set' - User selected a date/time and confirmed (positive button pressed)'dismissed' - Dialog was dismissed without selection (negative button, back button, or tap outside)'neutralButtonPressed' - Neutral button was pressed (typically "Clear" button on Android)Utility functions for creating standardized event parameters. These are primarily used internally but are exported for custom event handling.
/**
* Creates event parameters for date/time set events
* @param date - The selected date
* @param utcOffset - Timezone offset in minutes from UTC
* @returns Tuple of [event, date] for onChange handler
*/
function createDateTimeSetEvtParams(
date: Date,
utcOffset: number
): [DateTimePickerEvent, Date];
/**
* Creates event parameters for dismiss events
* @param date - The original date value
* @param utcOffset - Timezone offset in minutes from UTC
* @returns Tuple of [event, date] for onChange handler
*/
function createDismissEvtParams(
date: Date,
utcOffset: number
): [DateTimePickerEvent, Date];
/**
* Creates event parameters for neutral button events
* @param date - The original date value
* @param utcOffset - Timezone offset in minutes from UTC
* @returns Tuple of [event, date] for onChange handler
*/
function createNeutralEvtParams(
date: Date,
utcOffset: number
): [DateTimePickerEvent, Date];Usage Examples:
import {
createDateTimeSetEvtParams,
createDismissEvtParams,
createNeutralEvtParams
} from "@react-native-community/datetimepicker";
// Creating custom events (typically for testing or advanced use cases)
const selectedDate = new Date('2023-12-25');
const timezoneOffset = -480; // PST offset in minutes
// Create a "set" event
const [setEvent, setDate] = createDateTimeSetEvtParams(selectedDate, timezoneOffset);
console.log(setEvent.type); // 'set'
console.log(setEvent.nativeEvent.timestamp); // 1703462400000
console.log(setEvent.nativeEvent.utcOffset); // -480
// Create a "dismissed" event
const [dismissEvent, dismissDate] = createDismissEvtParams(selectedDate, timezoneOffset);
console.log(dismissEvent.type); // 'dismissed'
// Create a "neutral button" event
const [neutralEvent, neutralDate] = createNeutralEvtParams(selectedDate, timezoneOffset);
console.log(neutralEvent.type); // 'neutralButtonPressed'The onChange callback follows a consistent pattern across all platforms and usage modes.
/**
* Standard onChange handler signature
* @param event - Event object with type and native event data
* @param date - Selected date (undefined for dismiss events)
*/
type OnChangeHandler = (event: DateTimePickerEvent, date?: Date) => void;Complete onChange Implementation:
import React, { useState } from "react";
import DateTimePicker from "@react-native-community/datetimepicker";
function DatePickerWithEventHandling() {
const [date, setDate] = useState(new Date());
const [lastEventInfo, setLastEventInfo] = useState(null);
const handleDateChange = (event: DateTimePickerEvent, selectedDate?: Date) => {
// Log event details
console.log('Event type:', event.type);
console.log('Timestamp:', event.nativeEvent.timestamp);
console.log('UTC Offset:', event.nativeEvent.utcOffset);
console.log('Selected date:', selectedDate);
// Store event info for display
setLastEventInfo({
type: event.type,
timestamp: new Date(event.nativeEvent.timestamp),
utcOffset: event.nativeEvent.utcOffset,
selectedDate: selectedDate
});
// Handle different event types
switch (event.type) {
case 'set':
if (selectedDate) {
setDate(selectedDate);
console.log('Date updated to:', selectedDate.toISOString());
}
break;
case 'dismissed':
console.log('Picker dismissed without selection');
// Optionally hide picker or show message
break;
case 'neutralButtonPressed':
console.log('Clear/neutral button pressed');
// Optionally clear the date or show default
setDate(new Date()); // Reset to today
break;
}
};
return (
<DateTimePicker
value={date}
mode="date"
display="default"
onChange={handleDateChange}
/>
);
}The event system provides timezone information in the utcOffset field.
const handleDateChange = (event: DateTimePickerEvent, selectedDate?: Date) => {
const { timestamp, utcOffset } = event.nativeEvent;
// Convert timestamp to Date object
const eventDate = new Date(timestamp);
// Calculate timezone information
const offsetHours = Math.abs(utcOffset) / 60;
const offsetDirection = utcOffset < 0 ? '-' : '+';
const timezoneString = `UTC${offsetDirection}${offsetHours}`;
console.log(`Event occurred at ${eventDate.toISOString()} (${timezoneString})`);
// Handle timezone-aware date processing
if (selectedDate) {
// The selectedDate is already in the local timezone
console.log('Local time:', selectedDate.toLocaleString());
console.log('UTC time:', selectedDate.toISOString());
}
};Android implementations support an additional onError callback for handling native errors.
/**
* Error handler for Android native errors
* @param error - Error object from native Android code
*/
type OnErrorHandler = (error: Error) => void;Usage Example:
import { DateTimePickerAndroid } from "@react-native-community/datetimepicker";
DateTimePickerAndroid.open({
value: new Date(),
onChange: (event, date) => {
// Handle normal events
},
onError: (error) => {
console.error('Native Android error:', error.message);
// Common error scenarios:
switch (error.message) {
case 'Activity is null':
console.log('App is in background or activity destroyed');
break;
case 'Dialog already showing':
console.log('Another picker dialog is already open');
break;
default:
console.log('Unexpected error:', error);
}
},
});Different platforms may have slightly different event patterns:
iOS:
dismissed events are less common (typically only on modal dismissal)Android:
dismissed event when cancelledneutralButtonPressed available for custom neutral buttons (not in Material 3)Windows:
set and dismissed)import { Platform } from 'react-native';
const handleDateChange = (event: DateTimePickerEvent, selectedDate?: Date) => {
if (Platform.OS === 'ios') {
// iOS may fire multiple events during interaction
if (event.type === 'set') {
// Update UI immediately
setDate(selectedDate);
}
} else if (Platform.OS === 'android') {
// Android fires single event when dialog closes
switch (event.type) {
case 'set':
setDate(selectedDate);
hideAndroidPicker();
break;
case 'dismissed':
hideAndroidPicker();
break;
}
}
};Install with Tessl CLI
npx tessl i tessl/npm-react-native-community--datetimepicker