Date Picker | Calcite Design System

Date Picker is a calendar component used for choosing a day of a month.

Overview

Date Picker can be used to pick a day or range of days that will autofill an input. Date Picker is designed to work within a dropdown or statically within the interface.

Sample

Usage

Choosing a day
Choosing a range of days

Accessibility

Key	Function
`Space`	Selects the focused element. When the date is selected and contained in a parent component, such as `calcite-input-date-picker`, closes the component.
`Enter`	Selects the focused element. When the date is selected and contained in a parent component, such as `calcite-input-date-picker`, closes the component.
`Tab`	Moves focus between the component's elements. When the currently focused step is the date, focus will cycle to the previous month.
`Tab` and `Shift`	Moves focus between the component's elements. When the currently focused step is the previous month, focus will cycle to the date.
`Arrow up`	When focused on the year, increases the year value. When focused on the date, moves focus to the previous non-disabled week.
`Arrow down`	When focused on the year, decreases the year value. When focused on the date, moves focus to the next non-disabled week.
`Arrow left`	When focused on the year, moves the cursor to the left. When focused on the date, moves focus to previous non-disabled date.
`Arrow right`	When focused on the year, moves the cursor to the right. When focused on the date, moves focus to next non-disabled date.
`Home`	When focused on the year, moves the cursor to the first number. When focused on the date, moves focus to the first day of the selected month.
`End`	When focused on the year, moves the cursor to the last number. When focused on the date, moves focus to the last day of the selected month.
`Esc`	When contained in a parent component, such as `calcite-input-date-picker`, closes the component.

API reference

Properties

Property	Attribute	Description	Type	Default
activeDate		Specifies the component's active date.	`Date`
activeRange	active-range	When `range` is `true`, specifies the active `range`. Where `"start"` specifies the starting range date and `"end"` the ending range date.	`"start" \| "end"`
calendars	calendars	When `range` is `true`, specifies the number of calendars displayed.	`1 \| 2`	`2`
headingLevel	heading-level	Specifies the heading level number of the component's `heading` for proper document structure, without affecting visual styling.	`HeadingLevel`
layout	layout	Defines the component's layout.	`"horizontal" \| "vertical"`	`"horizontal"`
max	max	When the component resides in a form, specifies the latest allowed date (`"yyyy-mm-dd"`).	`string`
maxAsDate		Specifies the latest allowed date as a full date object (`new Date("yyyy-mm-dd")`).	`Date`
messageOverrides		Overrides individual strings used by the component.	`Record<string, unknown> \| undefined`
min	min	When the component resides in a form, specifies the earliest allowed date (`"yyyy-mm-dd"`).	`string`
minAsDate		Specifies the earliest allowed date as a full date object (`new Date("yyyy-mm-dd")`).	`Date`
monthStyle	month-style	Specifies the component's month style.	`"abbreviated" \| "wide"`	`"wide"`
numberingSystem	numbering-system	Specifies the Unicode numeral system used by the component for localization. This property cannot be dynamically changed.	`NumberingSystem`
proximitySelectionDisabled	proximity-selection-disabled	When `true`, disables the default behavior on the third click of narrowing or extending the range and instead starts a new range.	`boolean`	`false`
range	range	When `true`, activates the component's range mode to allow a start and end date.	`boolean`	`false`
scale	scale	Specifies the size of the component.	`"s" \| "m" \| "l"`	`"m"`
value	value	Specifies the selected date as a string (`"yyyy-mm-dd"`), or an array of strings for `range` values (`["yyyy-mm-dd", "yyyy-mm-dd"]`).	`string \| string[]`
valueAsDate		Specifies the selected date as a full date object (`new Date("yyyy-mm-dd")`), or an array containing full date objects (`[new Date("yyyy-mm-dd"), new Date("yyyy-mm-dd")]`).	`Date \| Date[]`

Styles

Name	Description
--calcite-date-picker-border-color	Specifies the component's border color.
--calcite-date-picker-corner-radius	Specifies the component's border radius.
--calcite-date-picker-range-calendar-divider-color	When `range` is `true`, specifies the divider color between the component's calendars.
--calcite-date-picker-week-header-text-color	Specifies the text color of the component's week header.
--calcite-date-picker-header-action-background-color	Specifies the background color of component`s header actions.
--calcite-date-picker-header-action-background-color-hover	Specifies the background color of component`s header actions when hovered.
--calcite-date-picker-header-action-background-color-press	Specifies the background color of component`s header actions when pressed.
--calcite-date-picker-header-action-text-color	Specifies the text color of the component's header actions.
--calcite-date-picker-header-action-text-color-press	Specifies the text color of the component's header actions when pressed.
--calcite-date-picker-year-text-color	Specifies the text color of the component's year and suffix.
--calcite-date-picker-month-select-font-size	Specifies the font size of the component's month selector.
--calcite-date-picker-month-select-text-color	Specifies the text color of the component's month selector.
--calcite-date-picker-month-select-icon-color	Specifies the icon color of the component's month selector.
--calcite-date-picker-month-select-icon-color-hover	Specifies the icon color of the component's month selector when hovered.
--calcite-date-picker-day-background-color	Specifies the background color of the component's day elements.
--calcite-date-picker-day-background-color-hover	Specifies the background color of the component's day elements when hovered.
--calcite-date-picker-day-text-color	Specifies the text color of the component's day elements.
--calcite-date-picker-day-text-color-hover	Specifies the text color of the component's day elements when hovered.
--calcite-date-picker-current-day-text-color	Specifies the text color of the component's current day.
--calcite-date-picker-day-background-color-selected	Specifies the background color of the component's selected day.
--calcite-date-picker-day-text-color-selected	Specifies the text color of the component's selected day elements.
--calcite-date-picker-day-range-text-color	Specifies the text color of component's selected day range.
--calcite-date-picker-day-range-background-color	Specifies the background color the component's selected day range.
--calcite-date-picker-day-outside-range-background-color-hover	Specifies the background color of the component's day elements outside the current range when hovered.
--calcite-date-picker-day-outside-range-text-color-hover	Specifies the text color of the component's day elements outside the current range when hovered.

Events

Name	Description	Behavior
calciteDatePickerChange	Fires when a user changes the component's date. For `range` events, use `calciteDatePickerRangeChange`.	bubblescomposed
calciteDatePickerRangeChange	Fires when a user changes the component's date `range`. For components without `range` use `calciteDatePickerChange`.	bubblescomposed

Methods

Name	Description	Signature
componentOnReady	Creates a promise that resolves once the component is fully loaded.	`componentOnReady(): Promise<this>`
setFocus	Sets focus on the component's first focusable element.	`setFocus(options?: FocusOptions): Promise<void>`