Input Date Picker | Calcite Design System

Input Date Picker contains a calendar component within an input used for choosing a day of a month.

Overview

Input Date Picker is an input-driven component containing the Date Picker.

Sample

Component comparison

Input Date Picker and Date Picker both help users choose dates, but serve different needs.

Input Date Picker

This component

Best for forms or workflows where a dedicated text input field is appropriate.

Includes a text input and a built-in calendar popup.

Date Picker

Alternative

Best for an inline calendar, or a calendar popup triggered by a custom UI element such as a filter Chip or Action.

Includes the calendar interface, but no built-in text input or trigger.

Usage

Choosing a day
Choosing a range of days

Best practices

Input Date Picker with range selection enabled with January 22 to February 8 selected.

Do enable range to allow users to select a start and end date.

Input Date Picker with dates outside the allowed range disabled

Do use min and max properties to restrict dates and prevent invalid date selections.

Do use the minAsDate and maxAsDate properties to restrict selectable dates using a Date object.

Input Date Picker using a single calendar.

Do consider a different layout or number of calendars to fit the picker within the available space.

Validation

Use validationMessage to provide guidance when an Input Date Pickers's status is "invalid". The validationMessage should explain how to fix the error and avoid generic messages such as “invalid value.”

Do use validationMessage to give users clear, actionable guidance when a value is invalid.

Consultation date Input Date Picker in an invalid state with a validation message stating that it is an invalid date.

Avoid using a vague validationMessage that doesn't give users enough context to correct the error.

Accessibility

For more detailed keyboard navigation, visit the Date Picker's keyboard navigation.

Key	Function
`Tab`	Moves focus in and out of the component.
`Tab` and `Shift`	Moves focus in and out of the component.
`Arrow down`	Opens and shifts focus to the `calcite-date-picker` component.
`Esc`	When the `calcite-date-picker` component is `open`, closes the component and shifts focus back to the `calcite-input-date-picker`.

API reference

Properties

Property	Attribute	Description	Type	Default
calendars	calendars	When `range` is `true`, specifies the number of calendars displayed.	`1 \| 2`	`2`
clearable	clearable	When `true`, displays a clear button when the component has a value.	`boolean`	`false`
disabled	disabled	When `true`, prevents interaction and decreases the component's opacity.	`boolean`	`false`
flipPlacements		Specifies the component's fallback `placement` for slotted content when its initial or specified `placement` has insufficient space available.	`FlipPlacement[] \| undefined`
focusTrapDisabled	focus-trap-disabled	When `true`, prevents focus trapping.	`boolean`	`false`
form	form	Specifies the `id` of the component's associated form. When not set, the component is associated with its ancestor form element, if one exists.	`string \| undefined`
headingLevel	heading-level	Specifies the heading level number of the component's `heading` for proper document structure, without affecting visual styling.	`HeadingLevel \| undefined`
label	label	Specifies an accessible label for the component.	`string \| undefined`
labelText	label-text	Specifies the component's label text.	`string \| undefined`
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 \| undefined`
maxAsDate		Specifies the latest allowed date as a full date object.	`Date \| undefined`
messageOverrides		Replace localized message strings with your own strings. Note: Individual message keys may change between releases.	`Record<string, unknown> \| undefined`
min	min	When the component resides in a form, specifies the earliest allowed date ("yyyy-mm-dd").	`string \| undefined`
minAsDate		Specifies the earliest allowed date as a full date object.	`Date \| undefined`
monthStyle	month-style	Specifies the component's month style.	`"abbreviated" \| "wide"`	`"wide"`
name	name	Specifies the name of the component. Required to pass the component's `value` on form submission.	`string \| undefined`
numberingSystem	numbering-system	Specifies the Unicode numeral system used by the component for localization. This property cannot be dynamically changed.	`NumberingSystem \| undefined`
open	open	When `true`, displays the `calcite-date-picker` component.	`boolean`	`false`
overlayPositioning	overlay-positioning	Specifies the type of positioning to use for overlaid content. `"absolute"` works for most cases - positioning the component inside of overflowing parent containers, which affects the container's layout. `"fixed"` is used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`.	`OverlayPositioning`	`"absolute"`
placeholder	placeholder	Specifies placeholder text for the component.	`string \| undefined`
placement	placement	Determines the `calcite-date-picker`'s placement relative to the input.	`MenuPlacement`	`"bottom-start"`
proximitySelectionDisabled	proximity-selection-disabled	When `true`, disables the default behavior on the third click of narrowing or extending the range. Instead starts a new range.	`boolean`	`false`
range	range	When `true`, activates a range for the component.	`boolean`	`false`
readOnly	read-only	When `true`, the component's `value` can be read, but controls are not accessible and the `value` cannot be modified.	`boolean`	`false`
required	required	When `true` and the component resides in a form, the component must have a `value` in order for the form to submit.	`boolean`	`false`
scale	scale	Specifies the size of the component.	`"s" \| "m" \| "l"`	`"m"`
status	status	Specifies the input field's status, which determines message and icons.	`Status`	`"idle"`
topLayerDisabled	top-layer-disabled	When `true` and the component is `open`, disables top layer placement. Only set this if you need complex z-index control or if top layer placement causes conflicts with third-party components.	`boolean`	`false`
validationIcon	validation-icon	Specifies the validation icon to display under the component.	`IconName \| boolean \| undefined`
validationMessage	validation-message	Specifies the validation message to display under the component.	`string \| undefined`
validityread-only		The component's current validation state.	`ValidityState`
value	value	Selected date as a string in ISO format (`"yyyy-mm-dd"`).	`string \| string[]`
valueAsDate		The component's `value` as a full date object.	`Date \| Date[] \| undefined`

Slots

Name	Description
label-content	A slot for rendering content next to the component's `labelText`.

Styles

Name	Description
--calcite-input-date-picker-actions-icon-color	Specifies the component's actions icon color.
--calcite-input-date-picker-actions-icon-color-hover	Specifies the component's actions icon color on hover.
--calcite-input-date-picker-background-color	Specifies the component's input background color.
--calcite-input-date-picker-border-color	Specifies the component's input border color.
--calcite-input-date-picker-calendar-actions-background-color	Specifies the background color of the component's calendar actions.
--calcite-input-date-picker-calendar-actions-background-color-hover	Specifies the background color of the component's calendar actions when hovered.
--calcite-input-date-picker-calendar-actions-background-color-press	Specifies the background color of the component's calendar actions when pressed.
--calcite-input-date-picker-calendar-actions-text-color	Specifies the text color of the component's calendar actions.
--calcite-input-date-picker-calendar-actions-text-color-press	Specifies the text color of the component's calendar actions when pressed.
--calcite-input-date-picker-calendar-border-color	Specifies the border color of the component's calendar.
--calcite-input-date-picker-calendar-corner-radius	Specifies the corner radius of the component's calendar.
--calcite-input-date-picker-calendar-current-day-text-color	Specifies the text color of the component's calendar current day element.
--calcite-input-date-picker-calendar-day-background-color	Specifies the background color of the component's calendar day elements.
--calcite-input-date-picker-calendar-day-background-color-hover	Specifies the background color of the component's calendar day elements when hovered.
--calcite-input-date-picker-calendar-day-current-text-color	deprecated in v3.3.1, removal target v6.0.0 - Use `--calcite-input-date-picker-calendar-current-day-text-color` instead. Specifies the text color of current day of the component's date-picker.
--calcite-input-date-picker-calendar-day-range-background-color	Specifies the background color of the component's calendar selected day range.
--calcite-input-date-picker-calendar-day-range-text-color	Specifies the text color of the component's calendar selected day range.
--calcite-input-date-picker-calendar-day-text-color-selected	Specifies the text color of component's calendar selected day.
--calcite-input-date-picker-calendar-day-outside-range-background-color-hover	Specifies the background color of the component's calendar day elements outside the current range when hovered.
--calcite-input-date-picker-calendar-day-outside-range-text-color-hover	Specifies the text color of the component's calendar day elements outside the current range when hovered.
--calcite-input-date-picker-calendar-day-text-color	Specifies the text color of the component's calendar day elements.
--calcite-input-date-picker-calendar-day-text-color-hover	Specifies the text color of the component's calendar day elements when hovered.
--calcite-input-date-picker-calendar-selected-background-color	Specifies the background color of the component's calendar selected day.
--calcite-input-date-picker-calendar-shadow	Specifies the component's calendar shadow.
--calcite-input-date-picker-calendar-icon-color	Specifies the component's calendar icon color.
--calcite-input-date-picker-calendar-icon-color-hover	Specifies the component's calendar icon color when hovered.
--calcite-input-date-picker-calendar-month-select-text-color	Specifies the text color of the component's calendar selected month.
--calcite-input-date-picker-calendar-range-divider-color	When `range` is `true`, specifies the divider color between the component's calendars.
--calcite-input-date-picker-calendar-text-color	Specifies the text color of the component's calendar week, year & suffix.
--calcite-input-date-picker-corner-radius	Specifies the component's input corner radius.
--calcite-input-date-picker-divider-color	When `range` is `true`, specifies the component's divider color between two inputs.
--calcite-input-date-picker-icon-color	Specifies the component's input icon color.
--calcite-input-date-picker-placeholder-text-color	Specifies the component's input placeholder text color.
--calcite-input-date-picker-shadow	Specifies the component's input shadow.
--calcite-input-date-picker-text-color	Specifies the component's input text color.
--calcite-input-date-picker-input-action-background-color	Specifies the background color of the input's `clearable` element.
--calcite-input-date-picker-input-action-background-color-hover	Specifies the background color of the input's `clearable` element when hovered.
--calcite-input-date-picker-input-action-background-color-press	Specifies the background color of the input's `clearable` element when pressed.
--calcite-input-date-picker-input-action-icon-color	Specifies the icon color of the input's `clearable` and toggle elements.
--calcite-input-date-picker-input-action-icon-color-hover	Specifies the icon color of the input's `clearable` and toggle elements when hovered.
--calcite-input-date-picker-input-action-icon-color-press	Specifies the icon color of the input's `clearable` and toggle elements when pressed.

Events

Name	Description	Behavior
calciteInputDatePickerBeforeClose	Fires when the component is requested to be closed and before the closing transition begins.	bubblescomposed
calciteInputDatePickerBeforeOpen	Fires when the component is added to the DOM but not rendered, and before the opening transition begins.	bubblescomposed
calciteInputDatePickerChange	Fires when the component's `value` changes.	bubblescomposed
calciteInputDatePickerClose	Fires when the component is closed and animation is complete.	bubblescomposed
calciteInputDatePickerOpen	Fires when the component is opened and animation is complete.	bubblescomposed

Methods

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