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

android-imperative-api.mddocs/

Android Imperative API

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

Capabilities

DateTimePickerAndroid

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.

declare namespace DateTimePickerAndroidType {
  const open: (args: AndroidNativeProps) => void;
  const dismiss: (mode: AndroidNativeProps['mode'], design?: AndroidNativeProps['design']) => Promise<boolean>;
}

declare const DateTimePickerAndroid: typeof DateTimePickerAndroidType;

Usage Examples:

import { DateTimePickerAndroid } from "@react-native-community/datetimepicker";

// Basic date picker
function showDatePicker() {
  DateTimePickerAndroid.open({
    value: new Date(),
    onChange: (event, date) => {
      if (event.type === 'set' && date) {
        console.log('Selected date:', date);
      }
    },
    mode: 'date',
    display: 'default',
  });
}

// Material Design 3 date picker with custom styling
function showMaterialDatePicker() {
  DateTimePickerAndroid.open({
    value: new Date(),
    onChange: (event, date) => {
      switch (event.type) {
        case 'set':
          console.log('Date selected:', date);
          break;
        case 'dismissed':
          console.log('Dialog dismissed');
          break;
        case 'neutralButtonPressed':
          console.log('Clear button pressed');
          break;
      }
    },
    mode: 'date',
    design: 'material',
    title: 'Select your birthday',
    fullscreen: false,
    initialInputMode: 'calendar',
    positiveButton: { label: 'OK', textColor: '#2196F3' },
    negativeButton: { label: 'Cancel', textColor: '#757575' },
    neutralButton: { label: 'Clear', textColor: '#FF5722' },
  });
}

// Time picker with constraints
function showTimePicker() {
  DateTimePickerAndroid.open({
    value: new Date(),
    onChange: (event, date) => {
      if (event.type === 'set' && date) {
        console.log('Selected time:', date.toTimeString());
      }
    },
    mode: 'time',
    is24Hour: true,
    minuteInterval: 15,
    onError: (error) => {
      console.error('Picker error:', error);
    },
  });
}

Open Method

Shows a native Android date/time picker dialog.

/**
 * Opens native Android date/time picker dialog
 * @param args - Configuration object with picker options
 * @returns void - Results are provided via onChange callback
 */
open: (args: AndroidNativeProps) => void;

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

  • Required Properties:

    • value: Date - The initially selected date/time
    • onChange: (event, date) => void - Callback for handling results

  • Mode and Display:

    • mode?: 'date' | 'time' - Type of picker to show
    • display?: 'spinner' | 'default' | 'clock' | 'calendar' - Visual style (not supported in Material 3)
    • design?: 'default' | 'material' - Use Material 3 or default Android pickers

  • Material 3 Options:

    • title?: string - Dialog title
    • fullscreen?: boolean - Show as fullscreen dialog
    • initialInputMode?: 'default' | 'keyboard' - Initial input method

  • Button Configuration:

    • positiveButton?: {label?: string, textColor?: ColorValue} - OK button
    • negativeButton?: {label?: string, textColor?: ColorValue} - Cancel button
    • neutralButton?: {label?: string, textColor?: ColorValue} - Clear button (not in Material 3)

  • Constraints:

    • minimumDate?: Date - Earliest selectable date
    • maximumDate?: Date - Latest selectable date
    • minuteInterval?: MinuteInterval - Minute step interval (not in Material 3)
    • is24Hour?: boolean - Use 24-hour time format
    • firstDayOfWeek?: DAY_OF_WEEK - Starting day of week for calendar

  • Timezone Support:

    • timeZoneOffsetInMinutes?: number - Force specific timezone offset
    • timeZoneName?: string - IANA timezone database name

  • Error Handling:

    • onError?: (error: Error) => void - Callback for native errors

Dismiss Method

Programmatically dismisses the currently shown picker dialog.

/**
 * Dismisses currently shown picker dialog
 * @param mode - The mode of picker to dismiss ('date' or 'time')
 * @param design - Optional design type ('default' or 'material') to specify which picker to dismiss
 * @returns Promise<boolean> - true if dialog was dismissed, false if none was showing
 */
dismiss: (mode: AndroidNativeProps['mode'], design?: AndroidNativeProps['design']) => Promise<boolean>;

Usage Examples:

// Dismiss date picker
const dismissed = await DateTimePickerAndroid.dismiss('date');
if (dismissed) {
  console.log('Date picker was dismissed');
} else {
  console.log('No date picker was showing');
}

// Dismiss time picker
await DateTimePickerAndroid.dismiss('time');

Event Handling

The onChange callback receives detailed event information:

type AndroidPickerChangeHandler = (
  event: DateTimePickerEvent,
  date?: Date
) => void;

type DateTimePickerEvent = {
  type: 'set' | 'dismissed' | 'neutralButtonPressed';
  nativeEvent: {
    timestamp: number;
    utcOffset: number;
  };
};

Event Types:

  • 'set' - User selected a date/time (positive button pressed)
  • 'dismissed' - Dialog was dismissed without selection (negative button or back button)
  • 'neutralButtonPressed' - Neutral button was pressed (typically "Clear" - not available in Material 3)

Material Design 3 Features

When using design: 'material', additional features are available:

// Material 3 specific properties
{
  design: 'material',
  title: 'Select Date',           // Custom dialog title
  fullscreen: false,              // Control fullscreen mode
  initialInputMode: 'calendar',   // Start with calendar or keyboard input
  // Note: neutralButton, minuteInterval, and display are not supported
}

Error Handling

The onError callback handles native Android errors:

DateTimePickerAndroid.open({
  value: new Date(),
  onChange: (event, date) => { /* handle success */ },
  onError: (error) => {
    console.error('Android picker error:', error.message);
    // Common errors:
    // - Activity is null
    // - Dialog already showing
    // - Invalid date range
  },
});

Platform Compatibility

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

// Safe cross-platform usage
import { Platform } from 'react-native';
import { DateTimePickerAndroid } from '@react-native-community/datetimepicker';

if (Platform.OS === 'android') {
  DateTimePickerAndroid.open({
    value: new Date(),
    onChange: handleChange,
    mode: 'date',
  });
}

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