@expo-react-native/datetimepicker

A TypeScript React Native date and time picker for iOS, Android, and Windows. Published under the expo-react-native organization. Theme-responsive (light/dark), with inline picker on iOS and dialog on Android.

Table of contents

• Installation
• Quick start
• Examples
• API reference
• Theme-responsive
• Platform behavior
• TypeScript
• Support the project
• Changelog
• License

Installation

npm install @expo-react-native/datetimepicker
# or
yarn add @expo-react-native/datetimepicker
# or
pnpm add @expo-react-native/datetimepicker
# or
bun add @expo-react-native/datetimepicker

iOS

cd ios && pod install && cd ..

Android

No extra step. The package is autolinked.

Windows

The library includes Windows support; ensure your React Native Windows project is set up.

Quick start

import React, { useState } from 'react';
import { Button, Platform } from 'react-native';
import DateTimePicker, { DateTimePickerAndroid } from '@expo-react-native/datetimepicker';

export default function App() {
  const [date, setDate] = useState(new Date());

  const onChange = (_event: unknown, selectedDate?: Date) => {
    if (selectedDate) setDate(selectedDate);
  };

  const openPicker = () => {
    if (Platform.OS === 'android') {
      DateTimePickerAndroid.open({
        value: date,
        mode: 'date',
        onChange,
      });
    }
  };

  return (
    <>
      {Platform.OS !== 'android' && (
        <DateTimePicker value={date} mode="date" onChange={onChange} />
      )}
      {Platform.OS === 'android' && (
        <Button title="Pick date" onPress={openPicker} />
      )}
    </>
  );
}

Examples

1. Date picker (inline on iOS, dialog on Android)

import DateTimePicker, { type DateTimePickerEvent } from '@expo-react-native/datetimepicker';

const [date, setDate] = useState(new Date());

<DateTimePicker
  value={date}
  mode="date"
  onChange={(event: DateTimePickerEvent, selectedDate?: Date) => {
    if (selectedDate) setDate(selectedDate);
  }}
/>

2. Time picker

const [time, setTime] = useState(new Date());

<DateTimePicker
  value={time}
  mode="time"
  is24Hour={true}
  onChange={(event, selectedTime) => {
    if (selectedTime) setTime(selectedTime);
  }}
/>

3. Date and time (iOS only)

On iOS you can use mode="datetime". On Android, use two separate pickers (date then time) or open the date picker first and then the time picker.

<DateTimePicker
  value={date}
  mode="datetime"
  onChange={(event, d) => d && setDate(d)}
/>

4. Android: imperative dialog with DateTimePickerAndroid

Use this when you want a button to open the picker instead of rendering it inline.

import { DateTimePickerAndroid } from '@expo-react-native/datetimepicker';

const openDatePicker = () => {
  DateTimePickerAndroid.open({
    value: date,
    mode: 'date',
    onChange: (event, selectedDate) => {
      if (event.type === 'set' && selectedDate) setDate(selectedDate);
    },
  });
};

const openTimePicker = () => {
  DateTimePickerAndroid.open({
    value: date,
    mode: 'time',
    is24Hour: true,
    onChange: (event, selectedTime) => {
      if (event.type === 'set' && selectedTime) setDate(selectedTime);
    },
  });
};

<Button title="Select date" onPress={openDatePicker} />
<Button title="Select time" onPress={openTimePicker} />

5. Handle dismiss and neutral button (Android)

DateTimePickerAndroid.open({
  value: date,
  mode: 'date',
  onChange: (event, selectedDate) => {
    if (event.type === 'set' && selectedDate) {
      setDate(selectedDate);
    } else if (event.type === 'dismissed') {
      // User closed without selecting
    } else if (event.type === 'neutralButtonPressed') {
      // Neutral button tapped (e.g. "Clear")
    }
  },
  neutralButton: { label: 'Clear' },
});

6. Minimum and maximum date

const minDate = new Date(2020, 0, 1);
const maxDate = new Date(2030, 11, 31);

<DateTimePicker
  value={date}
  mode="date"
  minimumDate={minDate}
  maximumDate={maxDate}
  onChange={(e, d) => d && setDate(d)}
/>

7. Theme-responsive (explicit light/dark)

Use the hook to pass the current app theme so the picker re-renders when the user switches appearance.

import DateTimePicker, { useDateTimePickerTheme } from '@expo-react-native/datetimepicker';

const { themeVariant } = useDateTimePickerTheme();

<DateTimePicker
  value={date}
  mode="date"
  themeVariant={themeVariant}
  onChange={(e, d) => d && setDate(d)}
/>

8. Fixed theme (light or dark)

<DateTimePicker
  value={date}
  mode="date"
  themeVariant="dark"
  onChange={(e, d) => d && setDate(d)}
/>

9. Android Material design

DateTimePickerAndroid.open({
  value: date,
  mode: 'date',
  design: 'material',
  title: 'Select date',
  onChange: (e, d) => d && setDate(d),
});

10. iOS display styles

// Compact (iOS 14+)
<DateTimePicker value={date} mode="date" display="compact" onChange={...} />

// Spinner
<DateTimePicker value={date} mode="date" display="spinner" onChange={...} />

// Inline (iOS 14+)
<DateTimePicker value={date} mode="date" display="inline" onChange={...} />

More copy-paste examples: docs/EXAMPLES.md.

11. Full screen example (date + time with platform check)

import React, { useState } from 'react';
import { View, Text, Button, Platform } from 'react-native';
import DateTimePicker, {
  DateTimePickerAndroid,
  type DateTimePickerEvent,
} from '@expo-react-native/datetimepicker';

export default function DateTimeScreen() {
  const [date, setDate] = useState(new Date());

  const onChange = (event: DateTimePickerEvent, selected?: Date) => {
    if (event.type === 'set' && selected) setDate(selected);
  };

  const showDatePicker = () => {
    if (Platform.OS === 'android') {
      DateTimePickerAndroid.open({
        value: date,
        mode: 'date',
        onChange,
      });
    }
  };

  const showTimePicker = () => {
    if (Platform.OS === 'android') {
      DateTimePickerAndroid.open({
        value: date,
        mode: 'time',
        is24Hour: true,
        onChange,
      });
    }
  };

  return (
    <View style={{ padding: 20 }}>
      <Text>{date.toLocaleString()}</Text>
      {Platform.OS === 'ios' ? (
        <>
          <DateTimePicker value={date} mode="date" onChange={onChange} />
          <DateTimePicker value={date} mode="time" onChange={onChange} />
        </>
      ) : (
        <>
          <Button title="Date" onPress={showDatePicker} />
          <Button title="Time" onPress={showTimePicker} />
        </>
      )}
    </View>
  );
}

API reference

Default export: DateTimePicker

React component. On iOS it renders an inline picker. On Android it opens a dialog when mounted (use DateTimePickerAndroid.open for button-triggered dialogs).

| Prop | Type | Default | Description | |------|------|---------|-------------| | value | Date | required | Current date/time. | | onChange | (event, date?) => void | — | Called when the user selects a date/time or dismisses. | | mode | 'date' \| 'time' \| 'datetime' \| 'countdown' (iOS), 'date' \| 'time' (Android) | 'date' | Picker mode. | | minimumDate | Date | — | Minimum selectable date. | | maximumDate | Date | — | Maximum selectable date. | | minuteInterval | 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 10 \| 12 \| 15 \| 20 \| 30 | — | Step for minutes (e.g. 5 for 0, 5, 10…). | | is24Hour | boolean | — | 24-hour format (Android time). | | themeVariant | 'light' \| 'dark' \| 'system' | 'system' | iOS appearance. Omit or 'system' = follow system. | | display | 'default' \| 'spinner' \| 'compact' \| 'inline' (iOS), 'default' \| 'spinner' \| 'clock' \| 'calendar' (Android) | 'default' | Picker style. | | locale | string | — | iOS locale. | | timeZoneName | string | — | IANA time zone (e.g. 'America/Los_Angeles'). | | disabled | boolean | false | iOS: disable the picker. | | positiveButton / negativeButton / neutralButton | { label?: string; textColor?: ColorValue } | — | Android dialog buttons. |

Additional props (e.g. testID, style) are passed through to the underlying view where supported.

DateTimePickerAndroid

Use on Android for imperative dialogs.

• DateTimePickerAndroid.open(props)
  Opens the picker. props match the component props (value, mode, onChange, minimumDate, maximumDate, is24Hour, design, title, etc.).

• DateTimePickerAndroid.dismiss(mode?, design?)
  Closes the picker. Returns Promise<boolean>.

Example:

DateTimePickerAndroid.open({
  value: date,
  mode: 'date',
  onChange: (event, d) => d && setDate(d),
});

Hooks and helpers

• useDateTimePickerTheme()
  Returns { themeVariant: 'light' | 'dark', isDark: boolean } from useColorScheme(). Use when you want the picker to follow the current app theme and re-render on scheme change.

• resolveThemeVariant(themeVariant?: ThemeVariant)
  Maps 'system' or undefined to undefined; 'light'/'dark' unchanged. Used internally; you typically use themeVariant or useDateTimePickerTheme().

Exported types

• DateTimePickerEvent, EvtTypes
• AndroidNativeProps, IOSNativeProps, WindowsNativeProps, BaseProps
• ThemeVariant, DateTimePickerResult
• DatePickerOptions, TimePickerOptions
• ButtonType, DAY_OF_WEEK, and others as needed.

Theme-responsive

• iOS: Omit themeVariant or set themeVariant="system" so the native picker uses the system appearance. Set themeVariant="light" or "dark" to fix the theme.
• Android: Material dialogs follow the app theme automatically.
• Explicit sync: Use useDateTimePickerTheme() and pass themeVariant={themeVariant} so the picker re-renders when the user switches light/dark mode.

Platform behavior

| Feature | iOS | Android | Windows | |--------|-----|---------|---------| | Inline picker | ✅ | ❌ (dialog when component mounted) | ✅ | | Dialog via API | — | ✅ DateTimePickerAndroid.open | — | | mode="datetime" | ✅ | Use date + time separately | — | | mode="countdown" | ✅ | ❌ | ❌ | | themeVariant | ✅ | N/A (follows app theme) | — | | display (compact/spinner/inline) | ✅ | ✅ (default/spinner/clock/calendar) | — |

TypeScript

The library is written in TypeScript. All public types are exported:

import type {
  DateTimePickerEvent,
  AndroidNativeProps,
  IOSNativeProps,
  ThemeVariant,
} from '@expo-react-native/datetimepicker';

Support the project

If this library helps you, consider supporting the maintainers with a one-time coffee.

Support Any Techie with a one-time coffee: buymeacoffee.com/anytechie.

The funding field in package.json lets npm and GitHub show a sponsor link.

Changelog

Version history and notable changes are in CHANGELOG.md.

Organization

This package is maintained by expo-react-native and hosted on npm as @expo-react-native/datetimepicker.

• Repository: github.com/Any-Techie/expo-react-native-datetimepicker
• Issues: github.com/Any-Techie/expo-react-native-datetimepicker/issues
• npm: npmjs.com/package/@expo-react-native/datetimepicker

License

MIT — see LICENSE for full text. Copyright (c) 2025 expo-react-native (Any Techie).