CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-react-native-community--datetimepicker

Cross-platform React Native date and time picker component with native iOS, Android, and Windows implementations.

Pending
Overview
Eval results
Files

event-system.mddocs/

Event System

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

Capabilities

DateTimePickerEvent

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;
  };
};

Event Types

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)

Event Creator Functions

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'

onChange Handler Pattern

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}
    />
  );
}

Timezone Handling

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());
  }
};

Error Event Handling (Android Only)

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);
    }
  },
});

Platform-Specific Event Behavior

Different platforms may have slightly different event patterns:

iOS:

  • Events fire immediately when user interacts with the picker
  • dismissed events are less common (typically only on modal dismissal)
  • Continuous updates during scrolling in spinner mode

Android:

  • Events fire when dialog is dismissed (either confirmed or cancelled)
  • Always includes dismissed event when cancelled
  • neutralButtonPressed available for custom neutral buttons (not in Material 3)

Windows:

  • Events similar to iOS with immediate feedback
  • Limited event types (primarily 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

docs

android-imperative-api.md

component-api.md

event-system.md

index.md

tile.json