Date picker

A date picker allows users to either manually enter a date or select a date from a calendar.

Examples

Basic

Required

To require users to select a date before continuing, use the requiredDateOptions.isRequired property.

A required date picker will be invalid when the text input is empty and either the text input loses focus or the date picker popover is closed.

The error message can be customized via the requiredDateOptions.emptyDateText property.

American format

Helper text

Select a date.

Min and max date

French

Controlled

Controlled required

Controlling the date picker calendar state

Props

DatePicker

The main date picker component.
*required
Name	Type	Default	Description
appendTo	HTMLElement \| ((ref?: HTMLElement) => HTMLElement) \| 'inline'	'inline'	The container to append the menu to. Defaults to 'inline'. If your menu is being cut off you can append it to an element higher up the DOM tree. Some examples: menuAppendTo={() => document.body}; menuAppendTo={document.getElementById('target')}
aria-label	string	'Date picker'	Accessible label for the date picker.
buttonAriaLabel	string	'Toggle date picker'	Accessible label for the button to open the date picker.
className	string		Additional classes added to the date picker.
dateFormat	(date: Date) => string	(date: Date) => `${date.getFullYear()}-${(date.getMonth() + 1).toString().padStart(2, '0')}-${date .getDate() .toString() .padStart(2, '0')}`	How to format the date in the text input.
dateParse	(value: string) => Date	(val: string) => (val.split('-').length === 3 ? new Date(`${val}T00:00:00`) : new Date(undefined))	How to parse the date in the text input.
helperText	React.ReactNode		Helper text to display alongside the date picker. Expects a HelperText component.
inputProps	TextInputProps	{}	Additional props for the text input.
invalidFormatText	string	'Invalid date'	Error message to display when the text input contains a non-empty value in an invalid format.
isDisabled	boolean	false	Flag indicating the date picker is disabled.
locale	No type info	undefined
onBlur	(event: any, value: string, date?: Date) => void	(): any => undefined	Callback called every time the text input loses focus.
onChange	(event: React.FormEvent<HTMLInputElement>, value: string, date?: Date) => void	(): any => undefined	Callback called every time the text input value changes.
placeholder	string	'YYYY-MM-DD'	String to display in the empty text input as a hint for the expected date format.
popoverProps	Partial<Omit<PopoverProps, 'appendTo'>>		Props to pass to the popover that contains the calendar month component.
requiredDateOptions	DatePickerRequiredObject		Options to customize the requirement of a date
style	No type info	{}
validators	((date: Date) => string)[]	[]	Functions that returns an error message if a date is invalid.
value	string	''	Value of the text input.

CalendarFormat

Additional properties that extend from and can be passed to the main component. These properties allow customizing the calendar formatting and aria-labels.
*required
Name	Type	Description
cellAriaLabel	(date: Date) => string	Accessible label for the date cells.
dayFormat	(date: Date) => React.ReactNode	How to format days in buttons in table cells.
inlineProps	CalendarMonthInlineProps	Props used to ensure accessibility when displaying the calendar month inline.
locale	string	If using the default formatters which locale to use. Undefined defaults to current locale. See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_identification_and_negotiation
longWeekdayFormat	(date: Date) => React.ReactNode	How to format days in header for screen readers.
monthFormat	(date: Date) => React.ReactNode	How to format months in month select.
nextMonthAriaLabel	string	Accessible label for the next month button.
prevMonthAriaLabel	string	Accessible label for the previous month button.
rangeStart	Date	Which date to start range styles from.
weekdayFormat	(date: Date) => React.ReactNode	How to format week days in header.
weekStart	0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| Weekday	Day of week that starts the week. 0 is Sunday, 6 is Saturday.
yearInputAriaLabel	string	Accessible label for the year input.

DatePickerRef

Allows finer control over the calendar's open state when a React ref is passed into the date picker component. Accessed via ref.current[property], e.g. ref.current.toggleCalendar().
*required
Name	Type	Description
isCalendarOpenrequired	boolean	Current calendar open status.
setCalendarOpenrequired	(isOpen: boolean) => void	Sets the calendar open status.
toggleCalendarrequired	(isOpen?: boolean) => void	Toggles the calendar open status. If no parameters are passed, the calendar will simply toggle its open status. If the isOpen parameter is passed, that will set the calendar open status to the value of the isOpen parameter. If the eventKey parameter is set to 'Escape', that will invoke the date pickers onEscapePress event to toggle the correct control appropriately.

DatePickerRequiredObject

Props that customize the requirement of a date
*required
Name	Type	Default	Description
emptyDateText	string		Error message to display when the text input is empty and the isRequired prop is also passed in.
isRequired	boolean		Flag indicating the date is required.

CSS variables

Expand or collapse column	Selector	Variable	Value

View source on GitHub