🚧🚧 Looking for collaborators and financial backers 🚧🚧

Please support maintenance of the module with a monthly donation or help us with issues and pull requests.

Become a backer on OpenCollective or sponsor us on GitHub Sponsors.

See this issue for context. Thank you!

<br> <br> <br> <br> <br> <br> <br> <br> <br> <br> <br> <br> <br> <br>

---

React Native DateTimePicker

This repository was moved out of the react native community GH organization, in accordance to this proposal. The module is still published on npm under the old namespace (as documented) but will be published under a new namespace at some point, with a major version bump.

[![npm downloads][npm-downloads-badge]][npm-downloads-link] ![Supports Android and iOS][support-badge] ![MIT License][license-badge]

React Native date & time picker component for iOS, Android and Windows (please note Windows is not actively maintained).

Screenshots

<details> <summary>Expand for screenshots</summary> <table> <tr><td colspan=2><strong>iOS</strong></td></tr> <tr> <td><p align="center"><img src="./docs/images/ios_date_new.png" height="420"/></p></td> <td><p align="center"><img src="./docs/images/ios_time.png" width="260" height="420"/></p></td> </tr> <tr><td colspan=2><strong>Android</strong></td></tr> <tr> <td><p align="center"><img src="./docs/images/android_date.png" width="200" height="400"/></p></td> <td><p align="center"><img src="./docs/images/android_time.png" width="200" height="400"/></p></td> </tr> <tr> <td><p align="center"><img src="./docs/images/android_material_date.jpg" width="200" height="400"/></p></td> <td><p align="center"><img src="./docs/images/android_material_time.jpg" width="200" height="400"/></p></td> </tr> <tr><td colspan=1><strong>Windows</strong></td></tr> <tr> <td><p align="center"><img src="./docs/images/windows_date.png" width="380" height="430"/></p></td> <td><p align="center"><img src="./docs/images/windows_time_2.png" width="380" height="430"/></p></td> </tr> <tr> <td><p align="center"><img src="./docs/images/windows_time_1.png" width="310" height="40"/></p></td> </tr> </table> </details>

Table of contents

• React Native DateTimePicker
  • Table of contents
  • Expo users notice
  • Getting started
  • Usage
  • Localization note
  • Android imperative API
  • Android styling
  • Props / params
    • mode (optional)
    • display (optional)
    • design (optional, Android only)
    • initialInputMode (optional, Android only)
    • title (optional, Android only)
    • fullscreen (optional, Android only)
    • startOnYearSelection (optional, Android only)
    • onValueChange (optional)
    • onDismiss (optional)
    • onNeutralButtonPress (optional, Android only)
    • onChange (optional, deprecated)
    • value (required)
    • maximumDate (optional)
    • minimumDate (optional)
    • timeZoneName (optional, iOS or Android only)
    • timeZoneOffsetInMinutes (optional, iOS or Android only)
    • timeZoneOffsetInSeconds (optional, Windows only)
    • dayOfWeekFormat (optional, Windows only)
    • dateFormat (optional, Windows only)
    • firstDayOfWeek (optional, Android and Windows only)
    • textColor (optional, iOS only)
    • accentColor (optional, iOS only)
    • themeVariant (optional, iOS only)
    • locale (optional, iOS only)
    • is24Hour (optional, Windows and Android only)
    • positiveButton (optional, Android only)
    • negativeButton (optional, Android only)
    • neutralButton (optional, Android only)
    • minuteInterval (optional)
    • style (optional, iOS only)
    • disabled (optional, iOS only)
    • view props (optional, iOS only)
    • onError (optional, Android only)
  • Testing with Jest
  • Migration from the older components
  • Contributing to the component
  • Manual installation
  • Running the example app

Requirements

The module supports the new React Native architecture (Fabric rendering of iOS components, and turbomodules on Android).

Expo users notice

This module is part of Expo Go - see docs. However, Expo Go may not contain the latest version of the module and therefore, the newest features and bugfixes may not be available. If you use Expo Go, use the command npx expo install @react-native-community/datetimepicker (not yarn or npm) to install this module - Expo will automatically install the latest version compatible with your Expo SDK (which may not be the latest version of the module available).

If you're using a Dev Client, rebuild the Dev Client after installing the dependencies.

If you're using the expo prebuild command and building your native app projects (e.g. with EAS Build or locally), you can use the latest version of the module.

Getting started

npm install @react-native-community/datetimepicker --save

or

yarn add @react-native-community/datetimepicker

Autolinking is not yet implemented on Windows, so manual installation is needed.

On iOS, run npx pod-install after installing. Then rebuild your project.

Usage

import DateTimePicker from '@react-native-community/datetimepicker';

<details> <summary>Expand for examples</summary>

We give two equivalent examples on how to use the package on all supported platforms.

Recommended imperative api usage on Android

While the component-approach as given in the second paragraph works on Android, the recommended approach is to use the imperative api given in the first paragraph.

Read more about the motivation in Android imperative API.

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

  const showMode = (currentMode) => {
    DateTimePickerAndroid.open({
      value: date,
      onValueChange: (event, selectedDate) => setDate(selectedDate),
      mode: currentMode,
      is24Hour: true,
    });
  };

  const showDatepicker = () => {
    showMode('date');
  };

  const showTimepicker = () => {
    showMode('time');
  };

  return (
    <SafeAreaView>
      <Button onPress={showDatepicker} title="Show date picker!" />
      <Button onPress={showTimepicker} title="Show time picker!" />
      <Text>selected: {date.toLocaleString()}</Text>
    </SafeAreaView>
  );
};

Component usage on iOS / Android / Windows

export const App = () => {
  const [date, setDate] = useState(new Date(1598051730000));
  const [mode, setMode] = useState('date');
  const [show, setShow] = useState(false);

  const showMode = (currentMode) => {
    setShow(true);
    setMode(currentMode);
  };

  const showDatepicker = () => {
    showMode('date');
  };

  const showTimepicker = () => {
    showMode('time');
  };

  return (
    <SafeAreaView>
      <Button onPress={showDatepicker} title="Show date picker!" />
      <Button onPress={showTimepicker} title="Show time picker!" />
      <Text>selected: {date.toLocaleString()}</Text>
      {show && (
        <DateTimePicker
          testID="dateTimePicker"
          value={date}
          mode={mode}
          is24Hour={true}
          onValueChange={(event, selectedDate) => setDate(selectedDate)}
          onDismiss={() => setShow(false)}
        />
      )}
    </SafeAreaView>
  );
};

</details>

Localization note

By localization, we refer to the language (names of months and days), as well as order in which date can be presented in a picker (month/day vs. day/month) and 12 / 24 hour-format.

On Android, the picker will be controlled by the system locale. If you wish to change it, see instructions here.

On iOS, use XCode, as [documented here](https://developer