or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

android-imperative-api.mdcomponent-api.mdevent-system.mdindex.md
tile.json

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

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@react-native-community/datetimepicker@8.4.x

To install, run

npx @tessl/cli install tessl/npm-react-native-community--datetimepicker@8.4.0

index.mddocs/

React Native DateTimePicker

React Native DateTimePicker provides cross-platform date and time picker components with native iOS, Android, and Windows implementations. It offers both declarative React components and imperative APIs, with comprehensive customization options including Material Design 3 support, timezone handling, and accessibility features.

Package Information

  • Package Name: @react-native-community/datetimepicker
  • Package Type: npm
  • Language: TypeScript/JavaScript
  • Installation: npm install @react-native-community/datetimepicker

Core Imports

import DateTimePicker, { 
  DateTimePickerAndroid,
  DateTimePickerEvent,
  EvtTypes,
  Event,
  ButtonType,
  IOSNativeProps,
  AndroidNativeProps,
  WindowsNativeProps,
  DatePickerOptions,
  TimePickerOptions,
  RCTDateTimePickerNative,
  NativeRef,
  createDateTimeSetEvtParams,
  createDismissEvtParams,
  createNeutralEvtParams
} from "@react-native-community/datetimepicker";

For CommonJS:

const DateTimePicker = require("@react-native-community/datetimepicker").default;
const { DateTimePickerAndroid } = require("@react-native-community/datetimepicker");

Basic Usage

import React, { useState } from "react";
import { View, Button } from "react-native";
import DateTimePicker from "@react-native-community/datetimepicker";

function DatePickerExample() {
  const [date, setDate] = useState(new Date());
  const [show, setShow] = useState(false);

  const onChange = (event, selectedDate) => {
    setShow(false);
    if (selectedDate) {
      setDate(selectedDate);
    }
  };

  return (
    <View>
      <Button title="Show Date Picker" onPress={() => setShow(true)} />
      {show && (
        <DateTimePicker
          value={date}
          mode="date"
          display="default"
          onChange={onChange}
        />
      )}
    </View>
  );
}

Architecture

React Native DateTimePicker is built around platform-specific implementations:

  • iOS Integration: Uses native UIDatePicker with support for various display modes (compact, inline, spinner)
  • Android Integration: Uses native DatePickerDialog and TimePickerDialog with Material Design 3 support
  • Windows Integration: Uses native CalendarDatePicker and TimePicker components
  • Cross-Platform API: Unified TypeScript interfaces that adapt to platform capabilities
  • Event System: Comprehensive event handling for user interactions, dismissals, and errors

The package provides two usage patterns:

  1. Declarative Component: Standard React component approach (recommended for iOS)
  2. Imperative API: Programmatic dialog control via DateTimePickerAndroid (recommended for Android)

Capabilities

Core DateTimePicker Component

Cross-platform React component providing native date and time selection with platform-specific display modes and comprehensive customization options.

declare const DateTimePicker: React.FC<
  IOSNativeProps | AndroidNativeProps | WindowsNativeProps
>;

type IOSNativeProps = Readonly<{
  value: Date;
  onChange?: (event: DateTimePickerEvent, date?: Date) => void;
  mode?: IOSMode;
  display?: IOSDisplay;
  locale?: string;
  minuteInterval?: MinuteInterval;
  timeZoneOffsetInMinutes?: number;
  timeZoneName?: string;
  textColor?: string;
  accentColor?: string;
  themeVariant?: 'dark' | 'light';
  disabled?: boolean;
  maximumDate?: Date;
  minimumDate?: Date;
}>;

type AndroidNativeProps = Readonly<{
  value: Date;
  onChange?: (event: DateTimePickerEvent, date?: Date) => void;
  mode?: AndroidMode;
  display?: Display;
  design?: Design;
  initialInputMode?: InputMode;
  title?: string;
  fullscreen?: boolean;
  is24Hour?: boolean;
  minuteInterval?: MinuteInterval;
  timeZoneOffsetInMinutes?: number;
  timeZoneName?: string;
  maximumDate?: Date;
  minimumDate?: Date;
  positiveButton?: ButtonType;
  neutralButton?: ButtonType;
  negativeButton?: ButtonType;
  firstDayOfWeek?: DAY_OF_WEEK;
  onError?: (error: Error) => void;
}>;

type WindowsNativeProps = Readonly<{
  value: Date;
  onChange?: (event: DateTimePickerEvent, date?: Date) => void;
  display?: Display;
  placeholderText?: string;
  dateFormat?: WindowsDateFormat;
  dayOfWeekFormat?: WindowsDayOfWeekFormat;
  firstDayOfWeek?: DAY_OF_WEEK;
  timeZoneOffsetInSeconds?: number;
  is24Hour?: boolean;
  minuteInterval?: number;
  accessibilityLabel?: string;
  maximumDate?: Date;
  minimumDate?: Date;
  timeZoneName?: string;
}>;

Component API

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.

interface DateTimePickerAndroidType {
  open: (args: AndroidNativeProps) => void;
  dismiss: (mode: AndroidNativeProps['mode']) => Promise<boolean>;
}

declare const DateTimePickerAndroid: DateTimePickerAndroidType;

Android Imperative API

Event System

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

type DateTimePickerEvent = {
  type: EvtTypes;
  nativeEvent: {
    timestamp: number;
    utcOffset: number;
  };
};

type EvtTypes = 'set' | 'neutralButtonPressed' | 'dismissed';

function createDateTimeSetEvtParams(
  date: Date,
  utcOffset: number
): [DateTimePickerEvent, Date];

function createDismissEvtParams(
  date: Date,
  utcOffset: number
): [DateTimePickerEvent, Date];

function createNeutralEvtParams(
  date: Date,
  utcOffset: number
): [DateTimePickerEvent, Date];

Event System

Event Creator Functions

Utility functions for creating standardized event parameters, primarily used internally but exported for custom event handling scenarios.

function createDateTimeSetEvtParams(
  date: Date,
  utcOffset: number
): [DateTimePickerEvent, Date];

function createDismissEvtParams(
  date: Date,
  utcOffset: number
): [DateTimePickerEvent, Date];

function createNeutralEvtParams(
  date: Date,
  utcOffset: number
): [DateTimePickerEvent, Date];

Core Types

import { FC, Ref, SyntheticEvent } from 'react';
import { ColorValue, NativeMethods, ViewProps } from 'react-native';

type IOSMode = 'date' | 'time' | 'datetime' | 'countdown';
type AndroidMode = 'date' | 'time';
type Display = 'spinner' | 'default' | 'clock' | 'calendar';
type IOSDisplay = 'default' | 'compact' | 'inline' | 'spinner';
type MinuteInterval = 1 | 2 | 3 | 4 | 5 | 6 | 10 | 12 | 15 | 20 | 30;
type Design = 'default' | 'material';
type InputMode = 'default' | 'keyboard';
type DAY_OF_WEEK = 0 | 1 | 2 | 3 | 4 | 5 | 6;

type WindowsDateFormat = 
  | 'day month year'
  | 'dayofweek day month'
  | 'longdate'
  | 'shortdate';

type WindowsDayOfWeekFormat = 
  | '{dayofweek.abbreviated(2)}'
  | '{dayofweek.abbreviated(3)}'
  | '{dayofweek.full}';

type ButtonType = {
  label?: string;
  textColor?: ColorValue;
};

type Event = SyntheticEvent<Readonly<{timestamp: number}>>;

type BaseOptions = {
  value: Date;
  onChange?: (event: DateTimePickerEvent, date?: Date) => void;
};

type DateOptions = BaseOptions & {
  maximumDate?: Date;
  minimumDate?: Date;
};

type TimeOptions = BaseOptions & {
  is24Hour?: boolean;
};

type DatePickerOptions = DateOptions & {
  display?: Display;
};

type TimePickerOptions = TimeOptions & {
  display?: Display;
};

type RCTDateTimePickerNative = NativeMethods;
type NativeRef = {
  current: Ref<RCTDateTimePickerNative> | null;
};