@react-native-community/datetimepicker

What is @react-native-community/datetimepicker?

@react-native-community/datetimepicker is a React Native module that provides a cross-platform Date and Time Picker component. It allows developers to easily integrate date and time selection functionality into their React Native applications, supporting both iOS and Android platforms.

What are @react-native-community/datetimepicker's main functionalities?

Date Picker

This feature allows users to select a date from a calendar interface. The code sample demonstrates how to display a date picker when a button is pressed and update the state with the selected date.

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

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

  const onChange = (event, selectedDate) => {
    const currentDate = selectedDate || date;
    setShow(false);
    setDate(currentDate);
  };

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

Time Picker

This feature allows users to select a time from a clock interface. The code sample demonstrates how to display a time picker when a button is pressed and update the state with the selected time.

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

const App = () => {
  const [time, setTime] = useState(new Date());
  const [show, setShow] = useState(false);

  const onChange = (event, selectedTime) => {
    const currentTime = selectedTime || time;
    setShow(false);
    setTime(currentTime);
  };

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

Date and Time Picker

This feature allows users to select both date and time from a combined interface. The code sample demonstrates how to display a date and time picker when a button is pressed and update the state with the selected date and time.

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

const App = () => {
  const [dateTime, setDateTime] = useState(new Date());
  const [show, setShow] = useState(false);

  const onChange = (event, selectedDateTime) => {
    const currentDateTime = selectedDateTime || dateTime;
    setShow(false);
    setDateTime(currentDateTime);
  };

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

Other packages similar to @react-native-community/datetimepicker

react-native-datepicker

react-native-datepicker is another popular package for date and time picking in React Native applications. It provides a customizable date and time picker component. Compared to @react-native-community/datetimepicker, it offers more styling options but may not be as tightly integrated with the native date and time pickers on iOS and Android.

react-native-modal-datetime-picker

react-native-modal-datetime-picker is a React Native module that provides a customizable modal date and time picker. It wraps the native date and time pickers in a modal, offering more flexibility in terms of UI customization. It is a good alternative if you need a modal-based picker with more styling options compared to @react-native-community/datetimepicker.

README

React Native DateTimePicker

React Native date & time picker component for iOS and Android

iOS
Android

Table of Contents

• React Native DateTimePicker - iOS - Android
  • Getting started
    • Manual installation
      • iOS
      • Android
  • General Usage
    • Basic usage with state
  • Props
    • mode (optional)
    • display (optional, Android only)
    • onChange (optional)
    • value (required)
    • maximumDate (optional)
    • minimumDate (optional)
    • timeZoneOffsetInMinutes (optional, iOS only)
    • locale (optional, iOS only)
    • is24Hour (optional, Android only)
    • minuteInterval (optional, iOS only)
  • Migration from the older components
    • DatePickerIOS
    • DatePickerAndroid
    • TimePickerAndroid
  • Contributing to the component
    • Clone, install
    • Tests
      • Jest
      • Detox
        • iOS
        • Android
    • Running the example app

Getting started

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

or

yarn add @react-native-community/datetimepicker

If you are using RN > 0.60, only run pod install from the ios directory. Then rebuild your project.

For RN < 0.60, you need to link the dependency using react-native link:

react-native link @react-native-community/datetimepicker

Then run pod install from the ios directory and rebuild your project.

Manual installation

iOS

1. Install CocoaPods, here the installation guide.

2. Inside the iOS folder run pod init, this will create the initial pod file.

3. Update your pod file to look like the following ( Remember to replace MyApp with your target name ):

   # Allowed sources
   source 'https://github.com/CocoaPods/Specs.git'
   
   target 'MyApp' do
     # As we use Swift, ensure that `use_frameworks` is enabled.
     use_frameworks!
   
     # Specific iOS platform we are targetting
     platform :ios, '8.0'
   
     # Point to the installed version
     pod 'RNDateTimePicker', :path => '../node_modules/@react-native-community/datetimepicker/RNDateTimePicker.podspec'
   
     # React/React-Native specific pods
     pod 'React', :path => '../node_modules/react-native', :subspecs => [
       'Core',
       'CxxBridge',      # Include this for RN >= 0.47
       'DevSupport',     # Include this to enable In-App Devmenu if RN >= 0.43
       'RCTText',
       'RCTNetwork',
       'RCTWebSocket',   # Needed for debugging
     ]
   
     # Explicitly include Yoga if you are using RN >= 0.42.0
     pod 'yoga', :path => '../node_modules/react-native/ReactCommon/yoga'
   
     # Third party deps podspec link
     pod 'DoubleConversion', :podspec => '../node_modules/react-native/third-party-podspecs/DoubleConversion.podspec'
     pod 'glog', :podspec => '../node_modules/react-native/third-party-podspecs/glog.podspec'
     pod 'Folly', :podspec => '../node_modules/react-native/third-party-podspecs/Folly.podspec'
   
   end
   

4. Run pod install inside the same folder where the pod file was created

5. npm run start

6. npm run start:ios

Android

1. Add the following lines to android/settings.gradle:

   include ':@react-native-community_datetimepicker'
   project(':@react-native-community_datetimepicker').projectDir = new File(rootProject.projectDir, '../node_modules/@react-native-community/datetimepicker/android')
   

2. Add the compile line to the dependencies in android/app/build.gradle:

   dependencies {
       ...
       implementation project(':@react-native-community_datetimepicker')
   }
   

3. Add the import and link the package in MainApplication.java:

   + import com.reactcommunity.rndatetimepicker.RNDateTimePickerPackage;
   
   public class MainApplication extends Application implements ReactApplication {
   
     @Override
     protected List<ReactPackage> getPackages() {
       @SuppressWarnings("UnnecessaryLocalVariable")
       List<ReactPackage> packages = new PackageList(this).getPackages();
       // Packages that cannot be autolinked yet can be added manually here, for example:
   +   packages.add(new RNDateTimePickerPackage());
       return packages;
     }
   }
   

General Usage

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

or

const DateTimePicker = require('@react-native-community/datetimepicker');

Basic usage with state

import React, {Component} from 'react';
import {View, Button, Platform} from 'react-native';
import DateTimePicker from '@react-native-community/datetimepicker';

export default class App extends Component {
  state = {
    date: new Date('2020-06-12T14:42:42'),
    mode: 'date',
    show: false,
  }

  setDate = (event, date) => {
    date = date || this.state.date;

    this.setState({
      show: Platform.OS === 'ios' ? true : false,
      date,
    });
  }

  show = mode => {
    this.setState({
      show: true,
      mode,
    });
  }

  datepicker = () => {
    this.show('date');
  }

  timepicker = () => {
    this.show('time');
  }

  render() {
    const { show, date, mode } = this.state;

    return (
      <View>
        <View>
          <Button onPress={this.datepicker} title="Show date picker!" />
        </View>
        <View>
          <Button onPress={this.timepicker} title="Show time picker!" />
        </View>
        { show && <DateTimePicker value={date}
                    mode={mode}
                    is24Hour={true}
                    display="default"
                    onChange={this.setDate} />
        }
      </View>
    );
  }
}

Props

mode (optional)

Defines the type of the picker.

List of possible values:

• "date" (default for iOS and Android)
• "time"
• "datetime" (iOS only)
• "countdown" (iOS only)

<RNDateTimePicker mode="time" />

display (optional, Android only)

Defines the visual display of the picker for Android and will be ignored for iOS.

List of possible values:

• "default"
• "spinner"
• "calendar" (only for date mode)
• "clock" (only for time mode)

<RNDateTimePicker display="spinner" />

onChange (optional)

Date change handler.

This is called when the user changes the date or time in the UI. It receives the event and the date as parameters.

setDate = (event, date) => {}

<RNDateTimePicker onChange={this.setDate} />

value (required)

Defines the date or time value used in the component.

<RNDateTimePicker value={new Date()} />

maximumDate (optional)

Defines the maximum date that can be selected.

<RNDateTimePicker maximumDate={new Date(2300, 10, 20)} />

minimumDate (optional)

Defines the minimum date that can be selected.

<RNDateTimePicker minimumDate={new Date(1950, 0, 1)} />

timeZoneOffsetInMinutes (optional, iOS only)

Allows changing of the timeZone of the date picker. By default it uses the device's time zone.

// GMT+1
<RNDateTimePicker timeZoneOffsetInMinutes={60} />

locale (optional, iOS only)

Allows changing of the locale of the component. By default it uses the device's locale.

<RNDateTimePicker locale="es-ES" />

is24Hour (optional, Android only)

Allows changing of the time picker to a 24 hour format.

<RNDateTimePicker is24Hour={true} />

minuteInterval (optional, iOS only)

The interval at which minutes can be selected. Possible values are: 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30

<RNDateTimePicker minuteInterval={10} />

Migration from the older components

RNDateTimePicker is the new common name used to represent the old versions of iOS and Android.

On Android, open picker modals will update the selected date and/or time if the prop value changes. For example, if a HOC holding state, updates the value prop. Previously the component used to close the modal and render a new one on consecutive calls.

DatePickerIOS

• initialDate is deprecated, use value instead.

  // Before
  <DatePickerIOS initialValue={new Date()} />
  

  // Now
  <RNDateTimePicker value={new Date()} />
  

• date is deprecated, use value instead.

  // Before
  <DatePickerIOS date={new Date()} />
  

  // Now
  <RNDateTimePicker value={new Date()} />
  

• onChange now returns also the date.

  // Before
  onChange = (event) => {}
  <DatePickerIOS onChange={this.onChange} />
  

  // Now
  onChange = (event, date) => {}
  <RNDateTimePicker onChange={this.onChange} />
  

• onDateChange is deprecated, use onChange instead.

  // Before
  setDate = (date) => {}
  <DatePickerIOS onDateChange={this.setDate} />
  

  // Now
  setDate = (event, date) => {}
  <RNDateTimePicker onChange={this.setDate} />
  

DatePickerAndroid

• date is deprecated, use value instead.

  // Before
  try {
    const {action, year, month, day} = await DatePickerAndroid.open({
      date: new Date()
    });
  } catch ({code, message}) {
    console.warn('Cannot open date picker', message);
  }
  

  // Now
  <RNDateTimePicker mode="date" value={new Date()} />
  

• minDate and maxDate are deprecated, use minimumDate and maximumDate instead.

  // Before
  try {
    const {action, year, month, day} = await DatePickerAndroid.open({
      minDate: new Date(),
      maxDate: new Date()
    });
  } catch ({code, message}) {
    console.warn('Cannot open date picker', message);
  }
  

  // Now
  <RNDateTimePicker mode="date" minimumDate={new Date()} maximumDate={new Date()} />
  

• dateSetAction is deprecated, use onChange instead.

  // Before
  try {
    const {action, year, month, day} = await DatePickerAndroid.open();
    if (action === DatePickerAndroid.dateSetAction) {
      // Selected year, month (0-11), day
    }
  } catch ({code, message}) {
    console.warn('Cannot open date picker', message);
  }
  

  // Now
  setDate = (event, date) => {
    if (date !== undefined) {
      // timeSetAction
    }
  }
  <RNDateTimePicker mode="date" onChange={this.setDate} />
  

• dismissedAction is deprecated, use onChange instead.

  // Before
  try {
    const {action, year, month, day} = await DatePickerAndroid.open();
    if (action === DatePickerAndroid.dismissedAction) {
      // Dismissed
    }
  } catch ({code, message}) {
    console.warn('Cannot open date picker', message);
  }
  

  // Now
  setDate = (event, date) => {
    if (date === undefined) {
      // dismissedAction
    }
  }
  <RNDateTimePicker mode="date" onChange={this.setDate} />
  

TimePickerAndroid

• hour and minute are deprecated, use value instead.

  // Before
  try {
    const {action, hour, minute} = await TimePickerAndroid.open({
      hour: 14,
      minute: 0,
      is24Hour: false, // Will display '2 PM'
    });
    if (action !== TimePickerAndroid.dismissedAction) {
      // Selected hour (0-23), minute (0-59)
    }
  } catch ({code, message}) {
    console.warn('Cannot open time picker', message);
  }
  

  // Now
  // It will use the hour and minute defined in date
  <RNDateTimePicker mode="time" value={new Date()} />
  

• timeSetAction is deprecated, use onChange instead.

  // Before
  try {
    const {action, hour, minute} = await TimePickerAndroid.open();
    if (action === TimePickerAndroid.timeSetAction) {
      // Selected hour (0-23), minute (0-59)
    }
  } catch ({code, message}) {
    console.warn('Cannot open time picker', message);
  }
  

  // Now
  setTime = (event, date) => {
    if (date !== undefined) {
      // Use the hour and minute from the date object
    }
  }
  <RNDateTimePicker mode="time" onChange={this.setTime} />
  

• dismissedAction is deprecated, use onChange instead.

  // Before
  try {
    const {action, hour, minute} = await TimePickerAndroid.open();
    if (action === TimePickerAndroid.dismissedAction) {
      // Dismissed
    }
  } catch ({code, message}) {
    console.warn('Cannot open time picker', message);
  }
  

  // Now
  setTime = (event, date) => {
    if (date === undefined) {
      // dismissedAction
    }
  }
  <RNDateTimePicker mode="time" onChange={this.setTime} />
  

Contributing to the component

Clone, install

git clone https://github.com/react-native-community/react-native-datetimepicker.git
cd react-native-datetimepicker
npm install

Tests

Jest

npm install
npm run test

Detox

Detox is a gray box end-to-end testing and automation library for mobile apps.

• Dependencies required

For cleaning all the detox builds just run npm run detox:clean.

iOS

• debug:

  # Debug requires to run Metro Bundler
  npm run start
  npm run detox:ios:build:debug
  npm run detox:ios:test:debug
  

• release:

  npm run detox:ios:build:release
  npm run detox:ios:test:release
  

Android

An existing Android emulator is required to match the name defined in detox.configurations.android.emu.debug.name and detox.configurations.android.emu.release.name inside the package.json.

• debug:

  # Debug requires to run Metro Bundler
  npm run start
  npm run detox:android:build:debug
  npm run detox:android:test:debug
  

• release:

  npm run detox:android:build:release
  npm run detox:android:test:release
  

Running the example app

1. Install required pods in example/ios by running pods install
2. Run npm start to start Metro Bundler
3. Run npm run start:ios or npm run start:android

Changelog

2.1.1

• Add countdown option to iOSMode types #31
• Added TS type definition file path to package.json #77
• Improved readme #33, #39, #46, #97