React Native DateTimePicker

React Native date & time picker component for iOS, Android and Windows.

iOS
Android
Windows

Table of Contents

• React Native DateTimePicker
  • Table of Contents
  • Getting started
    • RN >= 0.60
    • RN < 0.60
  • 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)
    • timeZoneOffsetInSeconds (optional, Windows only)
    • dayOfWeekFormat (optional, Windows only)
    • dateFormat (optional, Windows only)
    • firstDayOfWeek (optional, Windows only)
    • textColor (optional, iOS only)
    • locale (optional, iOS only)
    • is24Hour (optional, Windows and Android only)
    • neutralButtonLabel (optional, Android only)
    • minuteInterval (optional)
    • style (optional, iOS only)
  • Migration from the older components
    • DatePickerIOS
    • DatePickerAndroid
    • TimePickerAndroid
  • Contributing to the component
  • Manual installation
    • iOS
    • Android
    • Windows
  • Running the example app

Requirements

• Xcode >= 10

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.

RN >= 0.60

If you are using RN >= 0.60, only run npx pod-install. Then rebuild your project.

RN < 0.60

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

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

Then run npx pod-install and rebuild your project.

If this does not work, see Manual installation.

General Usage

importDateTimePickerfrom'@react-native-community/datetimepicker';

or

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

Basic usage with state

importReact,{useState}from'react';import{View,Button,Platform}from'react-native';importDateTimePickerfrom'@react-native-community/datetimepicker';exportconstApp=()=>{const[date,setDate]=useState(newDate(1598051730000));const[mode,setMode]=useState('date');const[show,setShow]=useState(false);constonChange=(event,selectedDate)=>{constcurrentDate=selectedDate||date;setShow(Platform.OS==='ios');setDate(currentDate);};constshowMode=currentMode=>{setShow(true);setMode(currentMode);};constshowDatepicker=()=>{showMode('date');};constshowTimepicker=()=>{showMode('time');};return(<View><View><ButtononPress={showDatepicker}title="Show date picker!"/></View><View><ButtononPress={showTimepicker}title="Show time picker!"/></View>{show&&(<DateTimePickertestID="dateTimePicker"value={date}mode={mode}is24Hour={true}display="default"onChange={onChange}/>)}</View>);};

Props

Please note that this library currently exposes functionality from UIDatePicker on iOS and DatePickerDialog + TimePickerDialog on Android, and CalendarDatePicker +TimePicker on Windows.

These native classes offer only limited configuration, while there are dozens of possible options you as a developer may need. It follows that if your requirement is not supported by the backing native views, this library will not be able to implement your requirement. When you open an issue with a feature request, please document if (or how) the feature can be implemented using the aforementioned native views. If those views do not support what you need, such feature requests will be closed as not actionable.

mode (optional)

Defines the type of the picker.

List of possible values:

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

<RNDateTimePickermode="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" - Show a default date picker (spinner/calendar/clock) based on mode and android version.
• "spinner"
• "calendar" (only for date mode)
• "clock" (only for time mode)

<RNDateTimePickerdisplay="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)=>{};<RNDateTimePickeronChange={this.setDate}/>;

value (required)

Defines the date or time value used in the component.

<RNDateTimePickervalue={newDate()}/>

maximumDate (optional)

Defines the maximum date that can be selected. Note that on Android, this only works for date mode because TimePicker does not support this.

<RNDateTimePickermaximumDate={newDate(2300,10,20)}/>

minimumDate (optional)

Defines the minimum date that can be selected. Note that on Android, this only works for date mode because TimePicker does not support this.

<RNDateTimePickerminimumDate={newDate(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<RNDateTimePickertimeZoneOffsetInMinutes={60}/>

timeZoneOffsetInSeconds (optional, Windows only)

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

// UTC+1<RNDateTimePickertimeZoneOffsetInSeconds={3600}/>

dayOfWeekFormat (optional, Windows only)

Sets the display format for the day of the week headers. Reference: https://docs.microsoft.com/en-us/uwp/api/windows.ui.xaml.controls.calendarview.dayofweekformat?view=winrt-18362#remarks

<RNDateTimePickerdayOfWeekFormat={'{dayofweek.abbreviated(2)}'}/>

dateFormat (optional, Windows only)

Sets the display format for the date value in the picker's text box. Reference: https://docs.microsoft.com/en-us/uwp/api/windows.globalization.datetimeformatting.datetimeformatter?view=winrt-18362#examples

<RNDateTimePickerdateFormat="dayofweek day month"/>

firstDayOfWeek (optional, Windows only)

Indicates which day is shown as the first day of the week.

<RNDateTimePickerfirstDayOfWeek={DAY_OF_WEEK.Wednesday}/>// The native parameter type is an enum defined in defined https://docs.microsoft.com/en-us/uwp/api/windows.globalization.dayofweek?view=winrt-18362 - meaning an integer needs to passed here (DAY_OF_WEEK).

textColor (optional, iOS only)

Allows changing of the textColor of the date picker.

<RNDateTimePickertextColor="red"/>

locale (optional, iOS only)

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

<RNDateTimePickerlocale="es-ES"/>

is24Hour (optional, Windows and Android only)

Allows changing of the time picker to a 24 hour format. By default, this value is decided automatcially based on the user's chosen locale and other preferences.

<RNDateTimePickeris24Hour={true}/>

neutralButtonLabel (optional, Android only)

Allows displaying neutral button on picker dialog. Pressing button can be observed in onChange handler as event.type === 'neutralButtonPressed'

<RNDateTimePickerneutralButtonLabel="clear"/>

minuteInterval (optional)

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

(On Windows, this can be any number between 0-59.)

<RNDateTimePickerminuteInterval={10}/>

style (optional, iOS only)

Sets style directly on picker component. By default, the picker height is fixed to 216px.

Please note that by default, picker's text color is controlled by the application theme (light / dark mode). In dark mode, text is white and in light mode, text is black.

This means that eg. if the device has dark mode turned on, and your screen background color is white, you will not see the picker. Please use the Appearance api to adjust the picker's background color so that it is visible, as we do in the example App or opt-out from dark mode.

<RNDateTimePickerstyle={{flex: 1}}/>

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<DatePickerIOSinitialValue={newDate()}/>

  // Now<RNDateTimePickervalue={newDate()}/>

• date is deprecated, use value instead.

  // Before<DatePickerIOSdate={newDate()}/>

  // Now<RNDateTimePickervalue={newDate()}/>

• onChange now returns also the date.

  // BeforeonChange=event=>{};<DatePickerIOSonChange={this.onChange}/>;

  // NowonChange=(event,date)=>{};<RNDateTimePickeronChange={this.onChange}/>;

• onDateChange is deprecated, use onChange instead.

  // BeforesetDate=date=>{};<DatePickerIOSonDateChange={this.setDate}/>;

  // NowsetDate=(event,date)=>{};<RNDateTimePickeronChange={this.setDate}/>;

DatePickerAndroid

• date is deprecated, use value instead.

  // Beforetry{const{action, year, month, day}=awaitDatePickerAndroid.open({date: newDate(),});}catch({code, message}){console.warn('Cannot open date picker',message);}

  // Now<RNDateTimePickermode="date"value={newDate()}/>

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

  // Beforetry{const{action, year, month, day}=awaitDatePickerAndroid.open({minDate: newDate(),maxDate: newDate(),});}catch({code, message}){console.warn('Cannot open date picker',message);}

  // Now<RNDateTimePickermode="date"minimumDate={newDate()}maximumDate={newDate()}/>

• dateSetAction is deprecated, use onChange instead.

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

  // NowsetDate=(event,date)=>{if(date!==undefined){// timeSetAction}};<RNDateTimePickermode="date"onChange={this.setDate}/>;

• dismissedAction is deprecated, use onChange instead.

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

  // NowsetDate=(event,date)=>{if(date===undefined){// dismissedAction}};<RNDateTimePickermode="date"onChange={this.setDate}/>;

TimePickerAndroid

• hour and minute are deprecated, use value instead.

  // Beforetry{const{action, hour, minute}=awaitTimePickerAndroid.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<RNDateTimePickermode="time"value={newDate()}/>

• timeSetAction is deprecated, use onChange instead.

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

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

• dismissedAction is deprecated, use onChange instead.

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

  // NowsetTime=(event,date)=>{if(date===undefined){// dismissedAction}};<RNDateTimePickermode="time"onChange={this.setTime}/>;

Contributing to the component

Please see CONTRIBUTING.md

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 sourcessource'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 targettingplatform:ios,'8.0'# Point to the installed versionpod'RNDateTimePicker',:path=>'../node_modules/@react-native-community/datetimepicker/RNDateTimePicker.podspec'# React/React-Native specific podspod'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.0pod'yoga',:path=>'../node_modules/react-native/ReactCommon/yoga'# Third party deps podspec linkpod'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 =newFile(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;
   }
   }

Windows

Add the DateTimePickerWindows project to your solution

1. Open the solution in Visual Studio 2019
2. Right-click solution icon in Solution Explorer > Add > Existing Project Select 'D:\pathToYourApp\node_modules@react-native-community\datetimepicker\windows\DateTimePickerWindows\DateTimePickerWindows.vcxproj'

windows/myapp.sln

Add a reference to DateTimePickerWindows to your main application project. From Visual Studio 2019:

Right-click main application project > Add > Reference... Check 'DateTimePickerWindows' from the 'Project > Solution' tab on the left.

pch.h

Add #include "winrt/DateTimePicker.h".

app.cpp

Add PackageProviders().Append(winrt::DateTimePicker::ReactPackageProvider()); before InitializeComponent();.

Running the example app

1. Install required pods in example/ios by running npx pod-install
2. Run npm start to start Metro Bundler
3. Run npm run start:ios or npm run start:android or npm run start:windows (or yarn run start:windows)