See this issue.
Support us with a monthly donation and help us continue our activities. Become a backer on OpenCollective or sponsor us on GitHub Sponsors.
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.
React Native date & time picker component for iOS, Android and Windows.
- React Native DateTimePicker
- Table of contents
- Expo users notice
- Getting started
- Usage
- Localization note
- Android imperative API
- Props / params
mode
(optional
)display
(optional
)onChange
(optional
)value
(required
)maximumDate
(optional
)minimumDate
(optional
)timeZoneOffsetInMinutes
(optional
,iOS or Android only
)timeZoneOffsetInSeconds
(optional
,Windows only
)dayOfWeekFormat
(optional
,Windows only
)dateFormat
(optional
,Windows only
)firstDayOfWeek
(optional
,Windows only
)textColor
(optional
,iOS only
)accentColor
(optional
,iOS only
)themeVariant
(optional
,iOS only
)locale
(optional
,iOS only
)is24Hour
(optional
,Windows and Android only
)positiveButtonLabel
(optional
,Android only
)negativeButtonLabel
(optional
,Android only
)neutralButtonLabel
(optional
,Android only
)minuteInterval
(optional
)style
(optional
,iOS only
)disabled
(optional
,iOS only
)onError
(optional
,Android only
)
- Migration from the older components
- Contributing to the component
- Manual installation
- Running the example app
- Only Android API level >=21 (Android 5), iOS >= 11 are supported.
- Tested with Xcode 13.0 and RN 0.66.3. Other configurations are very likely to work as well but have not been tested.
This module is part of Expo - see docs. However, Expo SDK may not contain the latest version of the module and therefore, the newest features and bugfixes may not be available in Expo. Use the command 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).
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.
If you are using RN >= 0.60, only run npx pod-install
. Then rebuild your project.
import DateTimePicker from '@react-native-community/datetimepicker';
Expand for examples
We give two equivalent examples on how to use the package on all supported platforms.
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 onChange = (event, selectedDate) => {
const currentDate = selectedDate;
setDate(currentDate);
};
const showMode = (currentMode) => {
DateTimePickerAndroid.open({
value: date,
onChange,
mode: currentMode,
is24Hour: true
})
};
const showDatepicker = () => {
showMode('date');
};
const showTimepicker = () => {
showMode('time');
};
return (
<View>
<View>
<Button onPress={showDatepicker} title="Show date picker!" />
</View>
<View>
<Button onPress={showTimepicker} title="Show time picker!" />
</View>
<Text>selected: {date.toLocaleString()}</Text>
</View>
);
}
export const App = () => {
const [date, setDate] = useState(new Date(1598051730000));
const [mode, setMode] = useState('date');
const [show, setShow] = useState(false);
const onChange = (event, selectedDate) => {
const currentDate = selectedDate;
setShow(false);
setDate(currentDate);
};
const showMode = (currentMode) => {
setShow(true);
setMode(currentMode);
};
const showDatepicker = () => {
showMode('date');
};
const showTimepicker = () => {
showMode('time');
};
return (
<View>
<View>
<Button onPress={showDatepicker} title="Show date picker!" />
</View>
<View>
<Button onPress={showTimepicker} title="Show time picker!" />
</View>
<Text>selected: {date.toLocaleString()}</Text>
{show && (
<DateTimePicker
testID="dateTimePicker"
value={date}
mode={mode}
is24Hour={true}
onChange={onChange}
/>
)}
</View>
);
}
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 to inform the OS about the locales your application supports. iOS will automatically display the correctly localized DateTimePicker as long as the target language is contained in project.pbxproj
.
If you use a library like i18next or react-localize-redux to manage your translations, it is sufficient to add your target languages as described in the Apple Documentation - but you are not required to add any localization keys (like, for example, the days of the week). iOS will automatically display the correct localized strings as long as the target language is contained in
project.pbxproj
.
For testing your localization setup, refer here.
There is also the iOS-only locale prop that can be used to force locale in some cases but its usage is discouraged due to not working robustly in all picker modes (note the mixed month and day names). To the best of our knowledge, it works reliably in the spinner
mode.
For Expo, follow the localization docs.
On Android, you have a choice between using the component API (regular React component) or an imperative api (think of something like ReactNative.alert()
).
While the component API has the benefit of writing the same code on all platforms, to start we recommend using the imperative API on Android.
The params
is an object with the same properties as the component props documented in the next paragraph. (This is also because the component api internally uses the imperative one.)
import { DateTimePickerAndroid } from '@react-native-community/datetimepicker';
DateTimePickerAndroid.open(params: AndroidNativeProps)
DateTimePickerAndroid.dismiss(mode: AndroidNativeProps['mode'])
The reason we recommend the imperative API is: on Android, the date/time picker opens in a dialog, similar to ReactNative.alert()
from core react native. The imperative api models this behavior better than the declarative component api. While the component approach is perfectly functional, based on the issue tracker history, it appears to be more prone to introducing bugs.
Please note that this library currently exposes functionality from
UIDatePicker
on iOS and DatePickerDialog + TimePickerDialog on Android, andCalendarDatePicker
+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 the native views do not support what you need, such feature requests will be closed as not actionable.
Defines the type of the picker.
List of possible values:
"date"
(default foriOS
andAndroid
andWindows
)"time"
"datetime"
(iOS
only)"countdown"
(iOS
only)
<RNDateTimePicker mode="time" />
Defines the visual display of the picker. The default value is "default"
.
List of possible values for Android
"default"
- Show a default date picker (spinner/calendar/clock) based onmode
and Android version."spinner"
"calendar"
(only fordate
mode)"clock"
(only fortime
mode)
List of possible values for iOS (maps to preferredDatePickerStyle)
"default"
- Automatically pick the best style available for the current platform & mode."spinner"
- the usual appearance with a wheel from which you choose values"compact"
- Affects only iOS 14 and later. Will fall back to "spinner" if not supported."inline"
- Affects only iOS 14 and later. Will fall back to "spinner" if not supported.
<RNDateTimePicker display="spinner" />
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} />;
Defines the date or time value used in the component.
<RNDateTimePicker value={new Date()} />
Defines the maximum date that can be selected. Note that on Android, this only works for date
mode because TimePicker does not support this.
<RNDateTimePicker maximumDate={new Date(2300, 10, 20)} />
Defines the minimum date that can be selected. Note that on Android, this only works for date
mode because TimePicker does not support this.
<RNDateTimePicker minimumDate={new Date(1950, 0, 1)} />
Allows changing of the timeZone of the date picker. By default, it uses the device's time zone. We strongly recommend avoiding this prop on android because of known issues in the implementation (eg. #528).
// GMT+1
<RNDateTimePicker timeZoneOffsetInMinutes={60} />
Allows changing of the time zone of the date picker. By default it uses the device's time zone.
// UTC+1
<RNDateTimePicker timeZoneOffsetInSeconds={3600} />
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
<RNDateTimePicker dayOfWeekFormat={'{dayofweek.abbreviated(2)}'} />
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
<RNDateTimePicker dateFormat="dayofweek day month" />
Indicates which day is shown as the first day of the week.
<RNDateTimePicker firstDayOfWeek={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).
Allows changing of the textColor of the date picker. Has effect only when display
is "spinner"
.
<RNDateTimePicker textColor="red" />
Allows changing the accentColor (tintColor) of the date picker.
Has no effect when display
is "spinner"
.
Allows overriding system theme variant (dark or light mode) used by the date picker.
textColor
to make the picker dark-theme compatible
List of possible values:
"light"
"dark"
<RNDateTimePicker themeVariant="light" />
Allows changing the locale of the component. This affects the displayed text and the date / time formatting. By default, the device's locale is used. Please note using this prop is discouraged due to not working reliably in all picker modes. Prefer localization as documented in Localization note.
<RNDateTimePicker locale="es-ES" />
Allows changing of the time picker to a 24 hour format. By default, this value is decided automatcially based on the locale and other preferences.
<RNDateTimePicker is24Hour={true} />
Changes the label of the positive button.
<RNDateTimePicker positiveButtonLabel="OK!" />
Changes the label of the negative button.
<RNDateTimePicker positiveButtonLabel="Negative" />
Allows displaying neutral button on picker dialog.
Pressing button can be observed in onChange handler as event.type === 'neutralButtonPressed'
<RNDateTimePicker neutralButtonLabel="clear" />
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.
on iOS, this in only supported when display="spinner"
<RNDateTimePicker minuteInterval={10} />
Sets style directly on picker component. By default, the picker height is determined based on the display
prop.
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.
Alternatively, use the themeVariant
prop or opt-out from dark mode (discouraged).
<RNDateTimePicker style={{flex: 1}} />
If true, the user won't be able to interact with the view.
Callback that is called when an error occurs inside the date picker native code (such as null activity).
Please see migration.md
Please see CONTRIBUTING.md
Please see manual-installation.md
- Run
yarn
in repo root - Run
cd example
- Install required pods by running
npx pod-install
- Run
yarn start
to start Metro Bundler - Run
yarn run start:ios
oryarn run start:android
oryarn run start:windows
- To do any development on the library, open the example project (in the
example
folder) in xCode or Android Studio. The example project depends on the library code, which you can edit and observe any changes in the example project.