Date Picker

Date pickers enable a customer to select a single date or a date range, such as a payment date or a statement period requiring start and end dates. Date pickers are used to display past, present, or future dates. Use date pickers when you are asking the user for a date, a date range, or for scheduling tasks.

On this page

Import

Date Picker

Loading preview
Open in Storybook

Date Range Picker

Loading preview
Open in Storybook

Props

Date Picker Props

NameDescriptionDefault
label

Text that's used as the visual and accessible label for the component. If not provided, hide the component's built-in label. The visible label for the DateInput component.

string		-
aria-labelledby

The id of a label, which provides an accessible name for the component

string		-
id*

The id associated with the date picker.

string		-
name

The name used for form submission.

string		-
value

The value of the input for the date picker, in ISO format (controlled).

string		-
defaultValue

The default value of the input for the date picker, in ISO format (uncontrolled).

string		-
onChange

The handler called when the value of the input for the date picker changes.

((event: ChangeEvent<HTMLInputElement> | MouseEvent<HTMLButtonElement, MouseEvent>, value: DatePickerValueObject) => void)		-
onBlur

The handler called when the date picker input is blurred.

((event: FocusEvent<HTMLInputElement, Element>, value: DatePickerValueObject) => void)		-
isOpen

The open state of the calendar (controlled).

boolean		-
defaultIsOpen

The default open state of the calendar (uncontrolled).

boolean		-
onIsOpenChange

The handler called when the open state of the calendar changes.

((isOpen: boolean) => void)		-
disabledDates

List of disabled dates in the calendar.

DateStringOrDateStringRange[]		-
minDate

The minimum date allowed in the calendar, in ISO format.

string		-
maxDate

The maximum date allowed in the calendar, in ISO format.

string		-
circleDate

Configuration to outline a day in the calendar with a circle.

CalendarDayFlairConfig		-
squareDate

Configuration to outline a day in the calendar with a square.

CalendarDayFlairConfig		-
footer

The footer of the calendar.

ReactNode		-
shouldCreatePortal

Uses React portals to render date picker content in the document body to avoid clipping content

boolean		-
portalContainer

DOM element where the content should be rendered

HTMLElement | null		-
disabled

@deprecated use aria-disabled instead.

The disabled prop removes the element from the Accessibility Tree and prevents it from receiving focus. This is not recommended.

All DLS components are designed to use the aria-disabled property instead, which will style the component to be disabled, but still allow keyboard focus and screen reader interactivity.

boolean		-
aria-disabled

If true, styles component as disabled and prevents interactivity. Screen reader reads as "dimmed" or "disabled".

Booleanish		-
required

If true, indicates that the consumer must specify a value for the input before the owning form can be submitted.

boolean		-
className

Additional CSS class names to apply to the DateInput container.

string		-
lang

BCP 47 language tag to format the date input fields according to different cultural norms.

string		-
aria-describedby

ID of element providing additional description of the date input

string		-
status

Default, error, or success state. Will use the value provided by the context when wrapped in a FieldControl component.

FieldControlStatus		-
statusMessage

The status message to be displayed if status is 'success' or 'error'.

string		-
hint

Hint text to assist the user, displayed below the input.

string		-
isHintVisuallyHidden

If true, visually hides the hint text (it will still be accessible to screen readers)

boolean		-
showPlaceholder

Whether to show placeholders in the input fields

boolean		-
autocompleteSettings

AutoComplete settings for each of the input field parts

DateInputAutocompleteSettings		-
reactlytics
ReactlyticsProp		-
labelOverrides

Overrides for labels that have been defaulted in the component.

DatePickerLabelOverrides		-

Date Range Props

NameDescriptionDefault
label

Text that's used as the visual and accessible label for the component. If not provided, hide the component's built-in label. The visible label for the DateInput component.

string		-
aria-labelledby

The id of a label, which provides an accessible name for the component

string		-
value

The value of the input for the date range picker, in ISO format (controlled).

DateRangePickerValue		-
defaultValue

The default value of the input for the date range picker, in ISO format (uncontrolled).

DateRangePickerValue		-
onChange

The callback function that is called when the date range picker value changes.

((event: ChangeEvent<HTMLInputElement> | MouseEvent<HTMLButtonElement, MouseEvent>, value: DateRangePickerValueObject) => void)		-
onBlur

The handler called when the date range picker input is blurred.

((event: FocusEvent<HTMLInputElement, Element>, value: DateRangePickerValueObject) => void)		-
minDays

The minimum number of days that the selected range must span.

number		-
maxDays

The maximum number of days that the selected range can span.

number		-
shouldRetainEndDateOnChange

When set, retain the end date upon start date selection (when the start date is before the end date and the range is greater or equal to minDays).

TODO: transform v6 canRetainEndDateOnChange to shouldRetainEndDateOnChange in v7

boolean		-
shouldCreatePortal

Uses React portals to render date range picker content in the document body to avoid clipping content

boolean		-
portalContainer

DOM element where the content should be rendered

HTMLElement | null		-
disabled

@deprecated use aria-disabled instead.

The disabled prop removes the element from the Accessibility Tree and prevents it from receiving focus. This is not recommended.

All DLS components are designed to use the aria-disabled property instead, which will style the component to be disabled, but still allow keyboard focus and screen reader interactivity.

boolean		-
aria-disabled

If true, styles component as disabled and prevents interactivity. Screen reader reads as "dimmed" or "disabled".

Booleanish		-
footer

The footer of the calendar.

ReactNode		-
name

The name used for form submission.

string		-
required

If true, indicates that the consumer must specify a value for the input before the owning form can be submitted.

boolean		-
className

Additional CSS class names to apply to the DateInput container.

string		-
id*

The id associated with the date picker.

string		-
lang

BCP 47 language tag to format the date input fields according to different cultural norms.

string		-
aria-describedby

ID of element providing additional description of the date input

string		-
status

Default, error, or success state. Will use the value provided by the context when wrapped in a FieldControl component.

FieldControlStatus		-
statusMessage

The status message to be displayed if status is 'success' or 'error'.

string		-
hint

Hint text to assist the user, displayed below the input.

string		-
isHintVisuallyHidden

If true, visually hides the hint text (it will still be accessible to screen readers)

boolean		-
showPlaceholder

Whether to show placeholders in the input fields

boolean		-
reactlytics
ReactlyticsProp		-
isOpen

The open state of the calendar (controlled).

boolean		-
defaultIsOpen

The default open state of the calendar (uncontrolled).

boolean		-
onIsOpenChange

The handler called when the open state of the calendar changes.

((isOpen: boolean) => void)		-
disabledDates

List of disabled dates in the calendar.

DateStringOrDateStringRange[]		-
minDate

The minimum date allowed in the calendar, in ISO format.

string		-
maxDate

The maximum date allowed in the calendar, in ISO format.

string		-
circleDate

Configuration to outline a day in the calendar with a circle.

CalendarDayFlairConfig		-
squareDate

Configuration to outline a day in the calendar with a square.

CalendarDayFlairConfig		-
labelOverrides

Overrides for labels that have been defaulted in the component.

DateRangePickerLabelOverrides		-

Questions?

Connect with the DLS Team on Slack or by email.

Resources

Check out additional resources.