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
| Name | Type | Default | Description |
|---|---|---|---|
active | boolean | undefined | — | Active state of the field |
activeColor | string | undefined | — | Color of the component in its active state |
allowedDates | TCalendarAllowedDates | 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. |
allowedHours | number[] | undefined | — | Configures which hours are available for selection. |
allowedMinutes | number[] | undefined | — | Configures which minutes are available for selection. |
allowedSeconds | number[] | 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. |
appendIcon | IconValue | undefined | — | Icon in the append slot, after the content |
appendInnerIcon | IconValue | undefined | — | Icon in the inner append slot, after the content of the field |
autocomplete | string | 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. |
autofocus | boolean | undefined | — | Enables autofocus |
baseColor | string | undefined | — | Color of the component in its inactive state |
bgColor | string | undefined | — | Background color of the component |
centerAffix | boolean | undefined | — | Vertically center the appendInner, prependInner, clearIcon and label elements. |
clearable | boolean | undefined | — | Shows the clear button |
clearIcon | IconValue | undefined | 'remove' | Icon of the clear button |
color | string | undefined | — | Component color |
counter | string | number | boolean | undefined | — | Character counter. Accepts a boolean, a number or a string |
counterValue | number | ((value: any) => number) | undefined | — | Custom counter value. Either a number or a function computing it from the current value |
defaultDate | string | undefined | — | Date used by default when the model is empty (in the YYYY/MM/DD format). |
defaultYearMonth | string | undefined | — | Displayed year/month in the YYYY/MM format. The current year/month by default when v-model is not set. |
description | string | undefined | — | Description of the component, shown under the label |
dirty | boolean | undefined | — | Marks that the value of the field was changed by the user |
disabled | boolean | null | undefined | null | Disabled state |
displayFormat | string | ((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. |
emitImmediately | boolean | undefined | — | Emit the update:modelValue event right when the month or the year changes. Not available with multiple and range. |
error | boolean | undefined | — | Error state |
errorMessages | string | 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. |
events | TCalendarEvents | undefined | — | List of events shown in the calendar. Format: YYYY/MM/DD. |
eventsColor | TCalendarEventsColor | undefined | 'default' | Color of the events in the calendar. |
firstDayOfWeek | string | number | undefined | 1 | First day of the week (Monday by default). |
focused | boolean | undefined | — | Controls the focus state of the component. When true, the component is considered focused and may apply the corresponding styles or behavior. |
format12h | boolean | undefined | — | Shows the time in the 12-hour AM/PM format. |
header | boolean | undefined | — | Show the calendar header |
hideActions | boolean | undefined | true | Hide the confirmation buttons under the calendar — the chosen date is applied immediately. |
hideDetails | boolean | "auto" | undefined | — | Hides the details block (messages and hints). With the 'auto' value the block is hidden when there are no messages |
hideMessages | boolean | undefined | — | Hide the messages under the input |
hideSiblingMonth | boolean | undefined | — | Hide the days of the neighboring months in the calendar. |
hint | string | undefined | — | Hint text shown under the input |
iconColor | string | boolean | undefined | — | Icon color. Accepts a boolean or a color string |
id | string | undefined | — | Unique identifier of the component |
label | string | undefined | — | Label text of the component |
loading | string | boolean | undefined | — | Loading indicator for the component |
locale | string | 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. |
location | Anchor | undefined | 'bottom start' | Position of the dropdown calendar relative to the field. |
mask | string | undefined | 'DD.MM.YYYY' | Date/time format |
maxErrors | string | number | undefined | 1 | Maximum number of validation errors shown |
maxWidth | string | number | undefined | — | Maximum component width |
maxYearMonth | string | undefined | — | Forbid navigating the calendar past the given maximum date in the YYYY/MM format. |
menu | boolean | undefined | — | State of the dropdown calendar (v-model:menu). |
menuProps | CdsMenuProps | undefined | — | Props passed through to the CdsMenu component of the dropdown calendar. |
messages | string | readonly string[] | undefined | [] | Messages shown under the input |
minWidth | string | number | undefined | — | Minimum component width |
minYearMonth | string | undefined | — | Forbid navigating the calendar before the given minimum date in the YYYY/MM format. |
modelModifiers | Record<string, boolean> | undefined | — | v-model modifiers passed by Vue to process the field value |
modelValue | TDateInputValue | undefined | null | Value of the field: a string in the mask format, a { from, to } range object or an array of them with multiple/range. |
multiple | boolean | undefined | — | Allows selecting several dates. The v-model must be an array. |
name | string | undefined | — | Name of the input |
noUnset | boolean | undefined | — | Forbid resetting the date in the calendar. |
nowBtn | boolean | undefined | — | Shows the "Now" button. |
persistentClearable | boolean | undefined | — | Always show the clear button, not only on hover or focus |
persistentCounter | boolean | undefined | — | Always show the counter, not only while the field is in use |
persistentHint | boolean | undefined | — | Always show the hint, not only on focus |
persistentPlaceholder | boolean | undefined | — | Always show the placeholder instead of hiding it while the field is in use |
pickerProps | CdsDatePickerProps | undefined | — | Props passed through to the CdsDatePicker component. They win over the props of the field with the same name. |
placeholder | string | undefined | — | Placeholder text shown in an empty field |
prefix | string | undefined | — | Text prefix shown before the field value |
prependIcon | IconValue | undefined | — | Icon in the prepend slot, before the content |
prependInnerIcon | IconValue | undefined | 'calendar' | Icon in the inner prepend slot, before the content of the field |
range | boolean | undefined | — | Allows selecting a range of dates. The v-model must be an array. |
readonly | boolean | null | undefined | null | Read-only state |
reverse | boolean | undefined | — | Reverses the order of the elements inside the field |
role | string | undefined | — | ARIA role for the native input element |
rules | readonly 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. |
size | number | "xs" | "sm" | "md" | "lg" | "xl" | undefined | 'md' | Size of the component |
suffix | string | undefined | — | Text suffix shown after the field value |
textColor | string | undefined | — | Text color of the component |
theme | string | undefined | — | Component theme |
timePickerProps | CdsTimePickerProps | undefined | — | Props passed through to the CdsTimePicker component. They win over the props of the field with the same name. |
todayBtn | boolean | undefined | — | Show the "Today" button in the calendar header |
type | string | 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. |
validateOn | ValidateOn | undefined | — | Changes the type of the event that triggers validation |
validationValue | any | — | Value used when applying the validation rules |
view | "Calendar" | "Years" | "Months" | undefined | 'Calendar' | Default calendar view. Possible values: 'Calendar', 'Years', 'Months'. |
width | string | number | undefined | — | Component width |
withSeconds | boolean | undefined | — | Adds seconds to the time selection. |
withTime | boolean | 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
| Name | Type | Description |
|---|---|---|
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
| Name | Type | Description |
|---|---|---|
actions | CdsDateInputActionsSlot | Confirmation buttons under the calendar (relevant with hide-actions="false"). |
append | CdsInputSlot | Adds an element after the input |
append-inner | CdsInputDefaultSlot | Slot added at the end of the input |
clear | CdsInputDefaultSlot & { 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 |
details | CdsInputSlot | Slot 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 |
loader | LoaderSlotProps | Slot for a custom loader (shown when the loading prop is true). |
message | CdsMessageSlot | Slot for customizing the content of a message |
messages | CdsInputSlot | Slot 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. |
prepend | CdsInputSlot | Adds an element before the input |
prepend-inner | CdsInputDefaultSlot | Slot added at the start of the input |
Exposed
| Name | Type | Description |
|---|---|---|
cancel | () => void | Cancels the selection, restores the previous value and closes the popup. |
controlRef | HTMLElement | undefined | Ref to the control of the input |
fieldIconColor | string | undefined | Icon color |
isDirty | boolean | Whether the input is dirty |
isDisabled | boolean | Whether the input is disabled |
isPure | boolean | Whether the input is pure |
isReadonly | boolean | Whether the input is read-only |
isValid | boolean | null | Whether the input is valid |
isValidating | boolean | Whether 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 | () => void | Confirms the date chosen in the calendar and closes the popup. |
validate | (silent?: boolean) => Promise<string[]> | Validates the input |