Datepicker

A simple and reusable component to work with or select a date or a range of dates.

Accessibility

  • Supports keyboard hotkeys: tab - to switch between inputs, arrows, monthyear select and day grid. escape to close datepicker dropdown.
  • When month and year selects focused, up and down causes dropdown to open and move to value, enter and space to choose selected year or month.
  • When day grid is focused, left, down right and up to move through the grid days. Enter to pick date.
  • When left or right arrow is focused, enter causes the same as click on this arrow.
  • Accessibility best practices for this component (aria-valuenow, aria-valuetext, aria-valuemin, aria-valuemax, role=datepicker).

Datepicker

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

Datepicker in a popover

Press the down arrow key to interact with the calendar and select a date. Press the escape button to close the calendar.


Press the down arrow key to interact with the calendar and select a date. Press the escape button to close the calendar.

Datepicker with quick select actions

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
Quick Select

Datepicker with overrides

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

TimePicker

Timezone picker

Overrides

Additionally, you can fully customize any part of the Datepicker through the overrides prop. The Datepicker consists of multiple subcomponents that are listed bellow and you can override each one of them. To help you identify the names of these subcomponents, you can highlight them through this selector:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
Quick Select

Note: You should always use longhand CSS properties. Mixing shorthands and longhands will lead into strange behaviors!

Calendar API

autoFocusCalendar boolean = false

Defines if the calendar is set to be focused on an initial render.

excludeDates nullable Array<Date> = null

A list of dates to disable.

ArrayDate

quickSelect boolean

Display a set of buttons for quickly choosing date ranges. range must be true as well.

filterDate nullable function = null

A filter function that is called to check the disabled state of a day. If false is returned the day is considered to be disabled.

Date => boolean

highlightedDate nullable Date = null

Indicates a highlighted date on hover and keyboard navigation

Date

includeDates nullable Array<Date> = null

A list of selectable dates.

ArrayDate

range boolean = false

Defines if a range of dates can be selected.

locale nullable any = null

A locale object. See date-fns for more details https://github.com/date-fns/date-fns/tree/master/src/locale.

any

maxDate nullable Date = null

A max date that is selectable.

Date

minDate nullable Date = null

A min date that is selectable.

Date

monthsShown number = 1

A number of months rendered in the calendar.

onDayClick function = () => undefined

Day's click event handler.

date required Date
event required Event
=> mixed

onDayMouseOver function = () => undefined

Day's mouseover event handler.

date required Date
event required Event
=> mixed

onDayMouseLeave function = () => undefined

Day's mouseleave event handler.

date required Date
event required Event
=> mixed

onMonthChange function = () => undefined

Event handler that is called when the current rendered month is changed.

date required Date
=> mixed

onYearChange function = () => undefined

Event handler that is called when the current rendered month's year is changed.

date required Date
=> mixed

onChange function = () => undefined

Event handler that is called when a new date is selected.

date union required One of
Date,
ArrayDate
=> mixed

overrides { Root: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, QuickSelectContainer: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, QuickSelectLabel: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, QuickSelectButtons: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, CalendarContainer: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, CalendarHeader: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, PrevButton: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, PrevButtonIcon: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, NextButton: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, NextButtonIcon: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, MonthSelect: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, YearSelect: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, MonthHeader: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, WeekdayHeader: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, Month: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, Week: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, Day: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, Input: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, Popover: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>> }<object> = {}

{ Root: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, QuickSelectContainer: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, QuickSelectLabel: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, QuickSelectButtons: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, CalendarContainer: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, CalendarHeader: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, PrevButton: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, PrevButtonIcon: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, NextButton: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, NextButtonIcon: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, MonthSelect: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, YearSelect: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, MonthHeader: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, WeekdayHeader: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, Month: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, Week: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, Day: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, Input: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, Popover: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>> }Object

peekNextMonth boolean = false

Defines if dates outside of the range of the current month are displayed.

trapTabbing boolean = false

Defines if tabbing inside the calendar is circled within it.

value union = null

Currently selected date.

One of
Date,
ArrayDate

Datepicker API

autoFocusCalendar boolean required

Defines if the calendar is set to be focused on an initial render.

excludeDates nullable Array<Date> required

A list of dates to disable.

ArrayDate

quickSelect boolean

Display a set of buttons for quickly choosing date ranges. range must be true as well.

filterDate nullable function required

A filter function that is called to check the disabled state of a day. If false is returned the day is considered to be disabled.

Date => boolean

highlightedDate nullable Date required

Indicates a highlighted date on hover and keyboard navigation

Date

includeDates nullable Array<Date> required

A list of selectable dates.

ArrayDate

range boolean required

Defines if a range of dates can be selected.

locale nullable any required

A locale object. See date-fns for more details https://github.com/date-fns/date-fns/tree/master/src/locale.

any

maxDate nullable Date required

A max date that is selectable.

Date

minDate nullable Date required

A min date that is selectable.

Date

monthsShown number required

A number of months rendered in the calendar.

onDayClick function required

Day's click event handler.

date required Date
event required Event
=> mixed

onDayMouseOver function required

Day's mouseover event handler.

date required Date
event required Event
=> mixed

onDayMouseLeave function required

Day's mouseleave event handler.

date required Date
event required Event
=> mixed

onMonthChange function required

Event handler that is called when the current rendered month is changed.

date required Date
=> mixed

onYearChange function required

Event handler that is called when the current rendered month's year is changed.

date required Date
=> mixed

onChange function = () => undefined

Event handler that is called when a new date is selected.

date union required One of
Date,
ArrayDate
=> mixed

overrides { Root: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, QuickSelectContainer: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, QuickSelectLabel: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, QuickSelectButtons: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, CalendarContainer: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, CalendarHeader: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, PrevButton: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, PrevButtonIcon: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, NextButton: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, NextButtonIcon: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, MonthSelect: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, YearSelect: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, MonthHeader: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, WeekdayHeader: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, Month: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, Week: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, Day: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, Input: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, Popover: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>> }<object> = {}

{ Root: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, QuickSelectContainer: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, QuickSelectLabel: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, QuickSelectButtons: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, CalendarContainer: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, CalendarHeader: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, PrevButton: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, PrevButtonIcon: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, NextButton: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, NextButtonIcon: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, MonthSelect: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, YearSelect: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, MonthHeader: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, WeekdayHeader: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, Month: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, Week: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, Day: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, Input: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>>, Popover: { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>><<T>> }Object

peekNextMonth boolean required

Defines if dates outside of the range of the current month are displayed.

trapTabbing boolean required

Defines if tabbing inside the calendar is circled within it.

value union = null

Currently selected date.

One of
Date,
ArrayDate

"aria-label" nullable string = null

"aria-labelledby" nullable string = null

"aria-describedby" nullable string = "datepicker--screenreader--message--input"

disabled boolean = false

error boolean = false

Renders UI in 'error' state.

placeholder string = "YYYY/MM/DD"

required boolean = false

formatDisplayValue nullable function = null

function
One of
Date,
ArrayDate
,
string
=> string

formatString string = "YYYY/MM/DD"

mountNode HTMLElement

Where to mount the popover

HTMLElement

onClose function

Called when calendar is closed

() => mixed

TimePicker API

format union

Render options in AM/PM format or 24 hour format. Defaults to 12 hour.

One of
"12",
"24"

onChange function

Callback for when time selection changes.

Date => mixed

overrides object

Select { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>>*

step number

Amount of seconds between each option time. Defaults to 900 (15 minutes).

value Date

Optional value that can be provided to fully control the component. If not provided, TimePicker will manage state internally. Expects a value in seconds. E.g. 3600 = 01:00.

Date

TimezonePicker API

date Date

If not provided, defaults to new Date(). Important to note that the timezone picker only displays options related to the provided date. Take Pacific Time for example. On March 9th, Pacific Time equates to the more specific Pacific Standard Time. On March 10th, it operates on Pacific Daylight Time. The timezone picker will never display PST and PDT together. If you need exact specificity, provide a date. Otherwise it will default to the relevant timezone at render.

Date

mapLabels function

Customize the option's label. Useful for translations and optionally mapping from 'America/Los_Angeles' to 'Pacific Time'.

$ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
=> Node

onChange function

Callback for when the timezone selection changes. Follows same pattern as Select component.

value required $ReadOnlyArray$ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
option nullable required $ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean
type required $KeysObject.freeze({ select: "select", remove: "remove", clear: "clear" })
=> mixed

overrides object

Select { component: ?ComponentType<<T>>, props: ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T>>*

value $ReadOnlyArray<$ReadOnly<object>>

Optional value that can be provided to fully control the component. If not provided, TimezonePicker will manage state internally.

$ReadOnlyArray$ReadOnly
id union One of
string,
number
label Node
disabled boolean
clearableValue boolean
isCreatable boolean