@element-public/react-datepicker NPM

Datepicker

Description

Datepicker provides a way for users to select a specific date or range of dates from a dialog or dropdown.

See live demos on storybook

Install bundle from npm-e

npm i @element-public/react-components @element-public/themes

Optional: install the component individually

npm i @element-public/react-datepicker @element-public/themes

Open ~/.npmrc in an editor and add the following line to enable the @element-public scope:

@element-public:registry=https://npm.platforms.engineering

Troubleshooting

See below if you have never installed a package from Bayer's npm-enterprise or run into the following error:

npm ERR! code E401
npm ERR! Unable to authenticate, your authentication token seems to be invalid.
npm ERR! To correct this please trying logging in again with:
npm ERR!     npm login

Setup an access token

See the devtools npm-e guide to learn how to create an access token if this is the first time you are using a npm-e package at Bayer or you do not have a line that starts with the following in your ~/.npmrc file:

//npm.platforms.engineering/:_authToken=

Keyboard Navigation

Date Input

esc - Closes calendar
ArrowDown - Opens the calender when input is focused
Enter - If focused on the clearable icon it will clear the date picker value, if in the input it will submit the form.

Calendar

While focused on a day arrow keys allow for navigation around the calender.
Enter` - Selects the focused day

Highlighted Dates

Dates can be highlighted in a number of ways. The highlighted dates schema includes the following fields:

field	description	example(s)
`includeDisabled`	Boolean that when set to true will highlight dates, even if they have been disabled.	Enable highlighting of disabled days: `{ includeDisabled: true }`
`dates`	Array of valid date objects, most useful for scattered highlighted dates.	Highlight today and a week from today (using date-dns add()): `{ dates: [new Date(), add(new Date(), {days: 7} ]}`.
`days`	Array of days of the week as integers from 0 to 6. This will highlight every day of the week specified for the visible date.	Highlight every Wednesday: `{ days: [3] }`
`daysOfMonth`	Array of days of the month as integers from 0 to 29-31. This will highlight every day of the month specified for the visible date.	Highlight the 1st and 15th of the month: `{ daysOfMonth: [1, 15] }`
`from` and `to`	Date objects that represent the start and end date of a range, most useful for a contiguous block of highlighted dates. If only one is supplied (either `from` or `to`) the other will be considered infinity.	Highlight every day before and including today: `{to: new Date()}` Highlight everything after (and including) today: `{from: new Date()}`
`ranges`	Array of objects that allows multiple `to`/`from` ranges to be specified with the same rules. This also allows a configuration where you can specify everything up to a date and also everything after a date, leaving a range of highlighted dates in between.	Only today is valid (using date-fns add()): `{ ranges: [ {to: add(new Date(), {days: -1})}, {from: add(new Date(), {days: 1} ]}`
`customPredictor`	Custom function that will be called during evaluation.	Highlight even days: `{ customPredictor: date => date.getDate() % 2 === 0 }`

Please note: All dates are inclusive and date comparisons ignore time.

Disabled Dates

Disabled dates share a similar schema as highlighted dates. The disabled dates schema includes the following fields:

field	description	example(s)
`dates`	Array of valid date objects, most useful for scattered disabled dates.	Disable today and a week from today (using date-dns add()): `{ dates: [new Date(), add(new Date(), {days: 7} ]}`.
`days`	Array of days of the week as integers from 0 to 6. This will disable every day of the week specified for the visible date.	Disable every Wednesday: `{ days: [3] }`
`daysOfMonth`	Array of days of the month as integers from 0 to 29-31. This will disable every day of the month specified for the visible date.	Disable the 1st and 15th of the month: `{ daysOfMonth: [1, 15] }`
`from` and `to`	Date objects that represent the start and end date of a range, most useful for a contiguous block of disabled dates. If only one is supplied (either `from` or `to`) the other will be considered infinity.	Disable every day before and including today: `{to: new Date()}` Disable everything after (and including) today: `{from: new Date()}`
`ranges`	Array of objects that allows multiple `to`/`from` ranges to be specified with the same rules. This also allows a configuration where you can specify everything up to a date and also everything after a date, leaving a range of disabled dates in between.	Only today is valid (using date-fns add()): `{ ranges: [ {to: add(new Date(), {days: -1})}, {from: add(new Date(), {days: 1} ]}`
`customPredictor`	Custom function that will be called during evaluation.	Disable even days: `{ customPredictor: date => date.getDate() % 2 === 0 }`

Please note: All dates are inclusive and date comparisons ignore time.

Calendar

The Calendar component may now be used separately for light-weight needs. Its features are limited and it is not intended as a full service calendar component at this time.

Date Formatting

Datepicker now uses date-fns for date formatting and supports the following tokens.

Unit	Pattern	Result examples	Notes
Era	G..GGG	AD, BC
	GGGG	Anno Domini, Before Christ	2
	GGGGG	A, B
Calendar year	y	44, 1, 1900, 2017	5
	yo	44th, 1st, 0th, 17th	5,7
	yy	44, 01, 00, 17	5
	yyy	044, 001, 1900, 2017	5
	yyyy	0044, 0001, 1900, 2017	5
	yyyyy	...	3,5
Local week-numbering year	Y	44, 1, 1900, 2017	5
	Yo	44th, 1st, 1900th, 2017th	5,7
	YY	44, 01, 00, 17	5,8
	YYY	044, 001, 1900, 2017	5
	YYYY	0044, 0001, 1900, 2017	5,8
	YYYYY	...	3,5
ISO week-numbering year	R	-43, 0, 1, 1900, 2017	5,7
	RR	-43, 00, 01, 1900, 2017	5,7
	RRR	-043, 000, 001, 1900, 2017	5,7
	RRRR	-0043, 0000, 0001, 1900, 2017	5,7
	RRRRR	...	3,5,7
Extended year	u	-43, 0, 1, 1900, 2017	5
	uu	-43, 01, 1900, 2017	5
	uuu	-043, 001, 1900, 2017	5
	uuuu	-0043, 0001, 1900, 2017	5
	uuuuu	...	3,5
Quarter (formatting)	Q	1, 2, 3, 4
	Qo	1st, 2nd, 3rd, 4th	7
	QQ	01, 02, 03, 04
	QQQ	Q1, Q2, Q3, Q4
	QQQQ	1st quarter, 2nd quarter, ...	2
	QQQQQ	1, 2, 3, 4	4
Quarter (stand-alone)	q	1, 2, 3, 4
	qo	1st, 2nd, 3rd, 4th	7
	qq	01, 02, 03, 04
	qqq	Q1, Q2, Q3, Q4
	qqqq	1st quarter, 2nd quarter, ...	2
	qqqqq	1, 2, 3, 4	4
Month (formatting)	M	1, 2, ..., 12
	Mo	1st, 2nd, ..., 12th	7
	MM	01, 02, ..., 12
	MMM	Jan, Feb, ..., Dec
	MMMM	January, February, ..., December	2
	MMMMM	J, F, ..., D
Month (stand-alone)	L	1, 2, ..., 12
	Lo	1st, 2nd, ..., 12th	7
	LL	01, 02, ..., 12
	LLL	Jan, Feb, ..., Dec
	LLLL	January, February, ..., December	2
	LLLLL	J, F, ..., D
Local week of year	w	1, 2, ..., 53
	wo	1st, 2nd, ..., 53th	7
	ww	01, 02, ..., 53
ISO week of year	I	1, 2, ..., 53	7
	Io	1st, 2nd, ..., 53th	7
	II	01, 02, ..., 53	7
Day of month	d	1, 2, ..., 31
	do	1st, 2nd, ..., 31st	7
	dd	01, 02, ..., 31
Day of year	D	1, 2, ..., 365, 366	9
	Do	1st, 2nd, ..., 365th, 366th	7
	DD	01, 02, ..., 365, 366	9
	DDD	001, 002, ..., 365, 366
	DDDD	...	3
Day of week (formatting)	E..EEE	Mon, Tue, Wed, ..., Sun
	EEEE	Monday, Tuesday, ..., Sunday	2
	EEEEE	M, T, W, T, F, S, S
	EEEEEE	Mo, Tu, We, Th, Fr, Su, Sa
ISO day of week (formatting)	i	1, 2, 3, ..., 7	7
	io	1st, 2nd, ..., 7th	7
	ii	01, 02, ..., 07	7
	iii	Mon, Tue, Wed, ..., Sun	7
	iiii	Monday, Tuesday, ..., Sunday	2,7
	iiiii	M, T, W, T, F, S, S	7
	iiiiii	Mo, Tu, We, Th, Fr, Su, Sa	7
Local day of week (formatting)	e	2, 3, 4, ..., 1
	eo	2nd, 3rd, ..., 1st	7
	ee	02, 03, ..., 01
	eee	Mon, Tue, Wed, ..., Sun
	eeee	Monday, Tuesday, ..., Sunday	2
	eeeee	M, T, W, T, F, S, S
	eeeeee	Mo, Tu, We, Th, Fr, Su, Sa
Local day of week (stand-alone)	c	2, 3, 4, ..., 1
	co	2nd, 3rd, ..., 1st	7
	cc	02, 03, ..., 01
	ccc	Mon, Tue, Wed, ..., Sun
	cccc	Monday, Tuesday, ..., Sunday	2
	ccccc	M, T, W, T, F, S, S
	cccccc	Mo, Tu, We, Th, Fr, Su, Sa
AM, PM	a..aa	AM, PM
	aaa	am, pm
	aaaa	a.m., p.m.	2
	aaaaa	a, p
AM, PM, noon, midnight	b..bb	AM, PM, noon, midnight
	bbb	am, pm, noon, midnight
	bbbb	a.m., p.m., noon, midnight	2
	bbbbb	a, p, n, mi
Flexible day period	B..BBB	at night, in the morning, ...
	BBBB	at night, in the morning, ...	2
	BBBBB	at night, in the morning, ...
Hour 1-12	h	1, 2, ..., 11, 12
	ho	1st, 2nd, ..., 11th, 12th	7
	hh	01, 02, ..., 11, 12
Hour 0-23	H	0, 1, 2, ..., 23
	Ho	0th, 1st, 2nd, ..., 23rd	7
	HH	00, 01, 02, ..., 23
Hour 0-11	K	1, 2, ..., 11, 0
	Ko	1st, 2nd, ..., 11th, 0th	7
	KK	01, 02, ..., 11, 00
Hour 1-24	k	24, 1, 2, ..., 23
	ko	24th, 1st, 2nd, ..., 23rd	7
	kk	24, 01, 02, ..., 23
Minute	m	0, 1, ..., 59
	mo	0th, 1st, ..., 59th	7
	mm	00, 01, ..., 59
Second	s	0, 1, ..., 59
	so	0th, 1st, ..., 59th	7
	ss	00, 01, ..., 59
Fraction of second	S	0, 1, ..., 9
	SS	00, 01, ..., 99
	SSS	000, 001, ..., 999
	SSSS	...	3
Timezone (ISO-8601 w/ Z)	X	-08, +0530, Z
	XX	-0800, +0530, Z
	XXX	-08:00, +05:30, Z
	XXXX	-0800, +0530, Z, +123456	2
	XXXXX	-08:00, +05:30, Z, +12:34:56
Timezone (ISO-8601 w/o Z)	x	-08, +0530, +00
	xx	-0800, +0530, +0000
	xxx	-08:00, +05:30, +00:00	2
	xxxx	-0800, +0530, +0000, +123456
	xxxxx	-08:00, +05:30, +00:00, +12:34:56
Timezone (GMT)	O...OOO	GMT-8, GMT+5:30, GMT+0
	OOOO	GMT-08:00, GMT+05:30, GMT+00:00	2
Timezone (specific non-locat.)	z...zzz	GMT-8, GMT+5:30, GMT+0	6
	zzzz	GMT-08:00, GMT+05:30, GMT+00:00	2,6
Seconds timestamp	t	512969520	7
	tt	...	3,7
Milliseconds timestamp	T	512969520900	7
	TT	...	3,7
Long localized date	P	04/29/1453	7
	PP	Apr 29, 1453	7
	PPP	April 29th, 1453	7
	PPPP	Friday, April 29th, 1453	2,7
Long localized time	p	12:00 AM	7
	pp	12:00:00 AM	7
	ppp	12:00:00 AM GMT+2	7
	pppp	12:00:00 AM GMT+02:00	2,7
Combination of date and time	Pp	04/29/1453, 12:00 AM	7
	PPpp	Apr 29, 1453, 12:00:00 AM	7
	PPPppp	April 29th, 1453 at ...	7
	PPPPpppp	Friday, April 29th, 1453 at ...	2,7

See https://date-fns.org/v2.23.0/docs/format for more details.

Localization

Element's datepicker now supports i18n localization. We include all of the languages supported by date-fns including:

af, arDZ, arMA, arSA, arTN, az, be, bg, bn, bs, ca, cs, cy, da, de, deAT, el, enAU, enCA, enGB, enIN, enNZ, enUS, enZA, eo, es, et, eu, faIR, fi, fr, frCA, frCH, gd, gl, gu, he, hi, hr, ht, hu, hy, id, is, it, ja, ka, kk, kn, ko, lb, lt, lv, mk, mn, ms, mt, nb, nl, nlBE, nn, pl, pt, ptBR, ro, ru, sk, sl, sq, sr, srLatn, sv, ta, te, th, tr, ug, uk, uz, vi, zhCN, zhTW.

Using a locale

import { de } from 'date-fns/locale';

<Datepicker locale={de}>

Datepicker Props

Name	Type	Default	Required	Description
alwaysOpen	boolean	false	false	Keep the calendar visible at all times.
calendarProps	object	undefined	false	Custom props to be passed to the calendar.
calendarType	string	'full'	false	Define the type of the calendar. `full` defaults to the `dd MMM yyyy` date format, `month-year` defaults to the `MMM yyyy` date formatAccepted Values: full, month-year
centuryBehavior	string	'age'	false	When typing a date, this will determine 2-digit year parsing behavior. A value of `forward-only` will always use current century, so `02/08/02` will parse to `02/08/2002`. A value of `age`, on the other hand is meant to assist age entry. It will use the current century until a certain point (see `centurySlidingOffset`), and then will revert to the previous century. For example `05/25/01` will parse to `05/25/2001`, while `02/08/76` will parse to `02/08/1976`.Accepted Values: age, forward-only
centurySlidingOffset	number	76	false	Only used when `centuryBehavior` is set to `age`. This will adjust the cutoff point where 2 digit dates will revert to the previous century to aid in typed age entry. The formula for the cutoff is `last 2 digits of the result of current year minus centuryCutoffOffset`. For example, using the year 2022 and the default value of 76 we would have `lastTwoDigits(2022 - 76) = 46`. So any 2 digit year of `45` or less will become `20XX` and any 2 digit year of `46` or more will become `19XX`. A value of `0` will disable the behavior, regardless of `centuryBehavior`. In 2023, the cutoff will be `47`, and so forth.
className	string	undefined	false	The css class name to be passed through to the component markup.
dayCellTemplate	function	day => day.date	false	A function for formatting the individual days of the calendar. It takes the date being rendered and returns content.
disableChangeMonth	boolean	false	false	Prevents the user from changing the month. Often used in conjunction with `disableChangeYear` to allow the user to only choose a date within the current month.
disableChangeYear	boolean	false	false	Prevents the user from changing the year. Often used in conjunction with `disableChangeMonth` to allow the user to only choose a date within the current month.
disableClearing	boolean	false	false	Prevent the datePicker from being cleared. It is suggested to use `readOnly` in conjunction with `disableClearing`.
disabled	boolean	false	false	If true, disable datePicker completely.
disabledDates	Object	undefined	false	An object describing dates to be disabled and non-interactive. The schema includes the following: `{ dates, days, daysOfMonth, from, to, ranges, customPredictor }`. Please see README for full schema description and examples. Note: All dates are inclusive and date comparisons ignore time.
format	string\|function	'dd MMM yyyy'	false	Date formatting string or function. For format strings we use `date-fns.format()`. See https://date-fns.org/v2.23.0/docs/format for more details.
fullMonthName	boolean	true	false	Display the full month name in the calendar interface. Note, this does not effect the date format.
highlightedDates	Object	undefined	false	An object describing dates to be highlighted. The schema includes the following: `{ includeDisabled, dates, days, daysOfMonth, from, to, ranges, customPredictor }`. Please see README for full schema description and examples. Note: All dates are inclusive and date comparisons ignore time.
hoisted	boolean	undefined	false	Controls if the component is rendered outside of the parent element (aka hoisted). This is now managed automatically and no longer needs to be explicitly set unless using a custom (non-element) components with a parent that has `overflow: hidden`.
id	string	undefined	false	Randomly generated id. May be overwritten.
inputTimeZone	string	undefined	false	The timezone that the input date is provided in (see `value`). If `outputTimeZone` is not set, the date will be returned as UTC. Supports international timezones. See https://www.iana.org/time-zones.
label	string	undefined	false	The input label.
locale	object	enUS	false	Language support object in the `i18n` format. A number of pre-built languages can be imported from the npm package `date-fns`.
maxDate	Date	undefined	false	The maximum date selectable. Dates later than this will be disabled.
maxQuickSelectYear	number	undefined	false	The maximum year that will be visible in the year select dropdown. Note, This does not disable dates later than this from being able to be selected (see `minDate`), it only affects what years are visible in the Select. Defaults to current year + 10.
minDate	Date	undefined	false	The minimum date selectable. Dates earlier than this will be disabled.
minQuickSelectYear	number	undefined	false	The minimum year visible in the year select dropdown. Note, This does not disable dates earlier than this from being able to be selected (see `minDate`), it only affects what years are visible in the Select. Defaults to current year - 10.
mondayFirst	boolean	false	false	Overrides the first day of the week to start on Monday.
openDate	date	undefined	false	If set, open on that date. Must be either a valid date object or a string that can be parsed by the date constructor.
outputTimeZone	string	undefined	false	The timezone the date will be converted to and formatted as when using `useUtc`. If `inputTimeZone` is not set, the date is assumed to already be in UTC time. Supports international timezones. See https://www.iana.org/time-zones.
parseFormats	string	"P"	false	One or more acceptable formats for typed input. The default value 'P' will accept a short locale formatted date. See https://date-fns.org/v2.28.0/docs/parse for parsing options. Note, the value of the `format` prop will automatically be accepted.
placeholder	string	undefined	false	Placeholder text for the input.
portalContainer	string\|React.ReactNode	'document.body'	false	The DOM element the children will render in. If a string is sent it should be a valid DOM query selector. If one is not sent, Portal will default to `document.body`.
readOnly	boolean	false	false	User will not be allowed to type the date and must select it from the calendar.
required	boolean	false	false	Sets html required attribute on input
resetCalendarOnClose	boolean	false	false	This will reset the `Calendar` view to the selected date (or today's date when no date has been selected). By default the calendar will remember the last visible date shown until the page is refreshed.
sideContent	object\|string\|function	undefined	false	Content to appear to the side of the `Calendar`. Can be used to display details for a selected date. Normally will appear to the right of the calendar, except when `rtl` is true, where it will appear to the left of the calendar.
textfieldProps	object	undefined	false	Props to be passed to the `Textfield` component. Accepts any valid `Textfield` props.
useUtc	boolean	false	false	Use UTC for time calculations.
value	date	undefined	false	Current value of the datePicker.
variant	string	'filled'	false	Applies the selected style to the internal textfield.Accepted Values: filled, outlined

Datepicker Deprecated Props

Name	Type	Default	Required	Deprecated	Description
filled	boolean	undefined	false	Use `variant='filled'` instead.	Apply filled style to the date picker input. Previously called primary.
outlined	boolean	undefined	false	Replaced by `variant='outlined'`	Apply outlined style to the date picker input. Previously called secondary.
primary	boolean	undefined	false	Replaced by `variant='outlined'`	Applies a filled style.
secondary	boolean	undefined	false	Replaced by `variant='outlined'`	Applies outlined style.
typeable	boolean	undefined	false	Please use `readOnly` instead.	The user will not be allowed to type the date and must select it from the calendar.

Datepicker Render Props

Name	Type	Default	Required	Description
headerContent	React.ReactNode	undefined	false	Content to appear immediately after the `Calendar` header.
leadingContent	React.ReactNode	undefined	false	Content to appear before the `Calendar` header.
trailingContent	React.ReactNode	undefined	false	Content to appear after the `Calendar`.

Datepicker Deprecated Render Props

Name	Type	Default	Required	Deprecated	Description
beforeCalendarHeader	React.ReactNode	undefined	false	Use `leadingContent` instead.	Content to appear before the header.

Datepicker Events

Name	Default	Required	Description
onChange	undefined	false	Fired when character is entered into text field and on select.
onClear	undefined	false	Fired when input is cleared with the 'x' button.
onClose	undefined	false	Fired when calendar is closed.
onOpen	undefined	false	Fired when calendar is opened.
onSelect	undefined	false	Fired when date is selected.
onSelectDisabled	undefined	false	Fired when disabled date is clicked
onSelectMonth	undefined	false	Fired when month is selected
onSelectYear	undefined	false	Fired when year is selected

Datepicker Deprecated Events

Name	Default	Required	Params	Deprecated	Description
onSelectDisable	undefined	false		This has been renamed to `onSelectDisabled` for consistency	Fired when disabled date is clicked

Datepicker Breaking Changes

Description
dayCellContent (removed): Renamed to `dayCellTemplate`.
format: `date-fns` uses different tokens than the previous version of Datepicker, format strings may need to be updated.
highlighted (removed): Renamed to `highlightedDates`
initialView (removed): No longer used.
inline (removed): Use `alwaysOpen` instead.
localization (removed): Use `locale` instead.
maximumView (removed): Use `disabledDates`.
minimumView (removed): Use `disabledDates`.

Calendar Props

Name	Type	Default	Required	Description
className	string	undefined	false	The css class name to be passed through to the component markup.
dayCellTemplate	function	day => day.date	false	A function for formatting the individual days of the calendar. It takes the date being rendered and returns content.
disableChangeMonth	boolean	false	false	Prevents the user from changing the month. Often used in conjunction with `disableChangeYear` to allow the user to only choose a date within the current month. An alternative to disabled dates.
disableChangeYear	boolean	false	false	Prevents the user from changing the year. Often used in conjunction with `disableChangeMonth` to allow the user to only choose a date within the current year. An alternative to disabled dates.
disabledDates	Object	undefined	false	One or more date ranges that are not selectable. Must be in the format: `{ranges: [{ from, to }]}` where from/to are valid javascript date objects.
floating	boolean	true	false	Make the calendar float using absolute positioning.
fullMonthName	boolean	true	false	To show the full month name.
highlightedDates	Object	undefined	false	An object describing pre-highlighted dates of the currently visible month. The object can include the following fields: `includeDisabled` = include dates that are outside of the current month in the highlighting. `dates` = an array of valid date objects to highlight, most useful for scattered highlighted dates. `from` and `to` = a valid start and end date range to highlight, most useful for a contiguous block of highlighted dates.
hoisted	boolean	undefined	false	Controls if the component is rendered outside of the parent element (aka hoisted). This is now managed automatically and no longer needs to be explicitly set unless using a custom (non-Element) component with a parent that has `overflow: hidden`.
isRtl	boolean	false	false	The current language is right-to-left.
locale	object	enUS	false	Language support object in the `i18n` format. A number of pre-built languages can be imported from the npm package `date-fns`.
maxDate	Date	undefined	false	The maximum date selectable. Dates later than this will be disabled.
maxQuickSelectYear	number	undefined	false	Note, This does not disable dates later than this from being able to be selected (see `minDate`), it only affects what years are visible in the Select. Defaults to current year + 10.
minDate	Date	undefined	false	The minimum date s