Skip to content

CdsDateInput

New in v4.0

A date field: a text field with a calendar icon that opens CdsDatePicker in a dropdown menu on click. The date can be picked with the mouse or typed on the keyboard — the value arrives as a string in the mask format (DD.MM.YYYY by default).

Storybook GitLab
Test coverage: 96% — good coverage
API in specs
123 / 123 props, events, slots and exposed members with a test
Test cases
105 unit · 5 browser
Known bugs
9 pinned by an it.fails test
Code coverage
95.7% lines · 87.1% branches measured in v4.0.0-alpha.13
A11y (axe)
16 recommendations in 15 stories measured in v4.0.0-alpha.11

If the calendar is needed right on the page, without a field, take CdsDatePicker. For the time alone — CdsTimePicker, to pick from a ready list — CdsSelect.

Anatomy ​

The field is built on CdsTextInput, so the label, the description, the messages, clearing and validation work the same way. The calendar icon takes the prepend-inner zone and opens the menu — just like a click on the field itself.

Variations ​

Value and format ​

The date arrives in v-model as a string in the mask format. By default the placeholder shows the mask itself, so there is no need to state the format separately.

display-format changes only what the user sees: the model still keeps a string in mask. It accepts a mask (D MMMM YYYY) or a function receiving the native Date. If the date has to be stored differently — in ISO, for example — change mask: it defines both the storage and the parsing of the manual input.

Date and time ​

with-time adds a CdsTimePicker under the calendar and appends the time to the mask: DD.MM.YYYY turns into DD.MM.YYYY HH:mm (with-seconds — into DD.MM.YYYY HH:mm:ss). The value stays a single string, and the calendar and the clock change their own parts of it. The time picker settings are available right on the field — now-btn, format12h, allowed-hours, allowed-minutes — or as a whole through time-picker-props.

With the time on, the menu does not close on a click on a date: the user is still picking the hours. If you need an explicit finish, add :hide-actions="false" — the buttons will stand under the time picker.

Several dates and a range ​

multiple allows marking several dates — the model becomes an array of strings. range switches the calendar to picking a period: the value arrives as a { from, to } object, and the menu stays open until both bounds are chosen. A set of dates and a range have no common time, so with-time does not work with them.

Confirmation buttons ​

By default the chosen date is applied at once and the menu closes. Pass :hide-actions="false" — and the choice becomes a draft: it gets into the model only after the "OK" button, while "Cancel" restores the previous value. The component emits save and cancel.

The actions slot replaces the pair of buttons with your own: it receives save, cancel and isPristine — the flag telling that nothing was changed in the calendar.

Manual input ​

update-on sets the moment the typed value is parsed and gets into the model: by default these are blur and enter. A string that cannot be parsed by mask (or by a string display-format) is ignored — the field restores the previous value. An empty array forbids keyboard input and leaves the calendar only.

The component does not impose an input mask — add one with a directive, using the lightweight (2.5 KB) Maska library, for example.

Date restrictions ​

The calendar props are available right on the field: allowed-dates leaves only the needed days available, min-year-month and max-year-month do not let the navigation go beyond the range.

States ​

disabled blocks both the field and the calendar, readonly forbids changes but keeps focus and copying, error-messages shows an error under the field.

The calendar and the menu ​

picker-props passes settings to the calendar — a header with the summary of the choice, for example, and menu-props and location control the dropdown menu.

Guidelines ​

Scenarios ​

A reporting period ​

The period lives in one field: range gives { from, to }, :hide-actions="false" turns the choice into a draft, and the preset buttons write into the same model — the calendar picks their value up.

A delivery date ​

The restrictions work together: allowed-dates leaves only the weekdays, min-year-month and max-year-month — the nearest two months. Manual input is turned off here on purpose: an unavailable day cannot be typed in, and display-format shows the date in words.

A date in a form ​

The field takes part in CdsForm on a par with the others: rules receive the same string value that lies in the model, so a "not in the past" check is a plain function. Limiting the navigation through min-year-month backs the rule up rather than replaces it.

API ​

Props

NameTypeDefaultDescription
activeboolean | undefined—Active state of the field
activeColorstring | undefined—Color of the component in its active state
allowedDatesTCalendarAllowedDates | undefined—Array of dates available in the calendar. When a function is used, it receives the date in the YYYY/MM/DD format and must return true or false.
allowedHoursnumber[] | undefined—Configures which hours are available for selection.
allowedMinutesnumber[] | undefined—Configures which minutes are available for selection.
allowedSecondsnumber[] | undefined—Configures which seconds are available for selection.
allowedTime((hr: number | null, min: number | null, sec: number | null) => boolean) | undefined—Configures which time is available for selection.
appendIconIconValue | undefined—Icon in the append slot, after the content
appendInnerIconIconValue | undefined—Icon in the inner append slot, after the content of the field
autocompletestring | undefined—Helps to influence browser suggestions. The suppress value changes the name attribute of the fields, and off relies on the browser to stop suggesting values on its own. Any other value is passed to the built-in autocomplete of the corresponding element.
autofocusboolean | undefined—Enables autofocus
baseColorstring | undefined—Color of the component in its inactive state
bgColorstring | undefined—Background color of the component
centerAffixboolean | undefined—Vertically center the appendInner, prependInner, clearIcon and label elements.
clearableboolean | undefined—Shows the clear button
clearIconIconValue | undefined'remove'Icon of the clear button
colorstring | undefined—Component color
counterstring | number | boolean | undefined—Character counter. Accepts a boolean, a number or a string
counterValuenumber | ((value: any) => number) | undefined—Custom counter value. Either a number or a function computing it from the current value
defaultDatestring | undefined—Date used by default when the model is empty (in the YYYY/MM/DD format).
defaultYearMonthstring | undefined—Displayed year/month in the YYYY/MM format. The current year/month by default when v-model is not set.
descriptionstring | undefined—Description of the component, shown under the label
dirtyboolean | undefined—Marks that the value of the field was changed by the user
disabledboolean | null | undefinednullDisabled state
displayFormatstring | ((date: Date) => string) | undefined—Display format of the date in the field. A mask ('D MMMM YYYY') or a function receiving the native Date and returning a string. By default the value is shown as is — in the mask format.
emitImmediatelyboolean | undefined—Emit the update:modelValue event right when the month or the year changes. Not available with multiple and range.
errorboolean | undefined—Error state
errorMessagesstring | readonly string[] | null | undefined[]Puts the component into the error state and passes custom error messages. They are merged with any checks defined in the rules prop. This field does not trigger validation.
eventsTCalendarEvents | undefined—List of events shown in the calendar. Format: YYYY/MM/DD.
eventsColorTCalendarEventsColor | undefined'default'Color of the events in the calendar.
firstDayOfWeekstring | number | undefined1First day of the week (Monday by default).
focusedboolean | undefined—Controls the focus state of the component. When true, the component is considered focused and may apply the corresponding styles or behavior.
format12hboolean | undefined—Shows the time in the 12-hour AM/PM format.
headerboolean | undefined—Show the calendar header
hideActionsboolean | undefinedtrueHide the confirmation buttons under the calendar — the chosen date is applied immediately.
hideDetailsboolean | "auto" | undefined—Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages
hideMessagesboolean | undefined—Hide the messages under the input
hideSiblingMonthboolean | undefined—Hide the days of the neighboring months in the calendar.
hintstring | undefined—Hint text shown under the input
iconColorstring | boolean | undefined—Icon color. Accepts a boolean or a color string
idstring | undefined—Unique identifier of the component
labelstring | undefined—Label text of the component
loadingstring | boolean | undefined—Loading indicator for the component
localestring | TDateLocale | undefined—Locale for the dates. A locale name ('ru' | 'en') or a TDateLocale object. The current locale from useLocale is taken by default, otherwise ru.
locationAnchor | undefined'bottom start'Position of the dropdown calendar relative to the field.
maskstring | undefined'DD.MM.YYYY'Date/time format
maxErrorsstring | number | undefined1Maximum number of validation errors shown
maxWidthstring | number | undefined—Maximum component width
maxYearMonthstring | undefined—Forbid navigating the calendar past the given maximum date in the YYYY/MM format.
menuboolean | undefined—State of the dropdown calendar (v-model:menu).
menuPropsCdsMenuProps | undefined—Props passed through to the CdsMenu component of the dropdown calendar.
messagesstring | readonly string[] | undefined[]Messages shown under the input
minWidthstring | number | undefined—Minimum component width
minYearMonthstring | undefined—Forbid navigating the calendar before the given minimum date in the YYYY/MM format.
modelModifiersRecord<string, boolean> | undefined—v-model modifiers passed by Vue to process the field value
modelValueTDateInputValue | undefinednullValue of the field: a string in the mask format, a { from, to } range object or an array of them with multiple/range.
multipleboolean | undefined—Allows selecting several dates. The v-model must be an array.
namestring | undefined—Name of the input
noUnsetboolean | undefined—Forbid resetting the date in the calendar.
nowBtnboolean | undefined—Shows the "Now" button.
persistentClearableboolean | undefined—Always show the clear button, not only on hover or focus
persistentCounterboolean | undefined—Always show the counter, not only while the field is in use
persistentHintboolean | undefined—Always show the hint, not only on focus
persistentPlaceholderboolean | undefined—Always show the placeholder instead of hiding it while the field is in use
pickerPropsCdsDatePickerProps | undefined—Props passed through to the CdsDatePicker component. They win over the props of the field with the same name.
placeholderstring | undefined—Placeholder text shown in an empty field
prefixstring | undefined—Text prefix shown before the field value
prependIconIconValue | undefined—Icon in the prepend slot, before the content
prependInnerIconIconValue | undefined'calendar'Icon in the inner prepend slot, before the content of the field
rangeboolean | undefined—Allows selecting a range of dates. The v-model must be an array.
readonlyboolean | null | undefinednullRead-only state
reverseboolean | undefined—Reverses the order of the elements inside the field
rolestring | undefined—ARIA role for the native input element
rulesreadonly ValidationRule[] | undefined[]Accepts an array of items of different types: functions, booleans and strings. Functions take the input value as an argument and must return either true / false, or a string with an error message. The input goes into the error state if a function returns false (or any value in the array is false) or is a string.
sizenumber | "xs" | "sm" | "md" | "lg" | "xl" | undefined'md'Size of the component
suffixstring | undefined—Text suffix shown after the field value
textColorstring | undefined—Text color of the component
themestring | undefined—Component theme
timePickerPropsCdsTimePickerProps | undefined—Props passed through to the CdsTimePicker component. They win over the props of the field with the same name.
todayBtnboolean | undefined—Show the "Today" button in the calendar header
typestring | undefined'text'Type of the native input
updateOn("enter" | "blur")[] | undefined['blur', 'enter']Events that apply the manually entered value. An empty array forbids manual input — the field becomes read-only.
validateOnValidateOn | undefined—Changes the type of the event that triggers validation
validationValueany—Value used when applying the validation rules
view"Calendar" | "Years" | "Months" | undefined'Calendar'Default calendar view. Possible values: 'Calendar', 'Years', 'Months'.
widthstring | number | undefined—Component width
withSecondsboolean | undefined—Adds seconds to the time selection.
withTimeboolean | undefined—Adds a time selection (CdsTimePicker) under the calendar and appends the time to the mask. Works for a single date only — ignored with multiple and range.

Events

NameTypeDescription
cancel[]The selection was cancelled by the cancel button.
navigation[payload: { year: number | undefined; month: number | undefined; }]Navigation to another month or year in the calendar.
rangeEnd[payload: { from: Partial<IRawDate>; to: Partial<IRawDate>; }]End of a date range selection.
rangeStart[value: Partial<IRawDate>]Start of a date range selection.
save[value: TDateInputValue]The value was confirmed — by a selection in the calendar or by the save button.
update:focused[focused: boolean]The focus state of the field changed (v-model:focused).
update:menu[value: boolean]The state of the dropdown calendar changed (v-model:menu).
update:modelValue[value: TDateInputValue]The value of the field changed (v-model).

Slots

NameTypeDescription
actionsCdsDateInputActionsSlotConfirmation buttons under the calendar (relevant with hide-actions="false").
appendCdsInputSlotAdds an element after the input
append-innerCdsInputDefaultSlotSlot added at the end of the input
clearCdsInputDefaultSlot & { props: Record<string, any>; }Slot for a custom clear icon (shown when the clearable prop is true).
description{ description: string | undefined; props: Record<string, any>; }Default slot of the CdsDescription component
detailsCdsInputSlotSlot for custom content that lets you customize how the messages are displayed
label{ label: string | undefined; props: Record<string, any>; }Default slot of the CdsLabel component
loaderLoaderSlotPropsSlot for a custom loader (shown when the loading prop is true).
messageCdsMessageSlotSlot for customizing the content of a message
messagesCdsInputSlotSlot for custom content that lets you customize how the messages are displayed
picker-description{ year: string | number | undefined; }Description in the calendar header.
picker-title{ date: string; }Title in the calendar header.
prependCdsInputSlotAdds an element before the input
prepend-innerCdsInputDefaultSlotSlot added at the start of the input

Exposed

NameTypeDescription
cancel() => voidCancels the selection, restores the previous value and closes the popup.
controlRefHTMLElement | undefinedRef to the control of the input
fieldIconColorstring | undefinedIcon color
isDirtybooleanWhether the input is dirty
isDisabledbooleanWhether the input is disabled
isPurebooleanWhether the input is pure
isReadonlybooleanWhether the input is read-only
isValidboolean | nullWhether the input is valid
isValidatingbooleanWhether the input is being validated
reset() => Promise<void>Resets the input to its initial state
resetValidation() => Promise<void>Resets the validation of the input
save() => voidConfirms the date chosen in the calendar and closes the popup.
validate(silent?: boolean) => Promise<string[]>Validates the input