Calendar
Basic Usage
Sun
Mon
Tue
Wed
Thu
Fri
Sat
date.value === ''Sun
Mon
Tue
Wed
Thu
Fri
Sat
date.value === []<script setup>
import { Calendar } from '@8ctavio/vergil/components'
import { useModel } from '@8ctavio/vergil'
const date = useModel(null, { shallow: true })
const dates = useModel([])
</script>
<template>
<!-- Single Selection -->
<Calendar v-model="date"/>
<!-- Multiple Selection -->
<Calendar v-model="dates"/>
</template>Modifiers
WARNING
If no modifier is used, Calendar does not support regular refs directly provided through v-model.
String
When the string modifier is present, the model value is handled as a date-only-form string ("YYYY-MM-DD") of the date time string format.
<Calendar v-model.string="date"/>Sun
Mon
Tue
Wed
Thu
Fri
Sat
date.value === ''Timestamp timestamp
When the timestamp modifier is present, the model value is handled as a timestamp.
<Calendar v-model.timestamp="date"/>Sun
Mon
Tue
Wed
Thu
Fri
Sat
date.value === NaNProps
Locale locale: Intl.LocalesArgument = 'en'
The locale prop conforms to the Intl.DateTimeFormat constructor's locales parameter.
<Calendar locale="es-MX"/>Dom
Lun
Mar
Mié
Jue
Vie
Sáb
Labels labels: Record<'month' | 'shortMonths' | 'shortWeekdays', string[]>
If custom month/weekday labels are required, they can be specified through the labels prop as an object of the following form:
type Labels = {
months: string[],
shortMonths: string[]
shortWeekdays: string[],
}- Short weekday labels are taken from the
shortWeekdaysarray, going from Sunday at index0to Saturday at index6. - Month (short) labels are taken from the
months(shortMonths) array, going from January at index0to December at index11.
First weekday first-weekday: (0 | 1 | 2 | 3 | 4 | 5 | 6) = 0
The first-weekday prop specifies the index of the weekday to be considered as the first day of the week by the calendar. Weekdays are considered to be indexed from Sunday through Saturday from 0 to 6.
<Calendar :first-weekday="1"/>Mon
Tue
Wed
Thu
Fri
Sat
Sun
Dates range min: CalendarDate = '1970-01-01'
max: CalendarDate = '2131-12-31'
The min and max props define an inclusive range of dates that can be selected. Individual dates outside the defined range are disabled. Months that do not include dates inside the defined range cannot be displayed.
For both props, dates can be specified as a string of the form 'YYYY-MM-DD', a timestamp, or a date object.
<Calendar min="2025-01-01" max="2025-12-31"/>Sun
Mon
Tue
Wed
Thu
Fri
Sat
Selected month and year selected-month: string
selected-year: string
The selected-month and selected-year props define which month and year to display initially when the calendar is mounted. If one of these props is not set, it will default to the current date's month or year, respectively.
For the selected-month prop, months are considered to be numbered from '1' through '12'.
If there are selected dates when the calendar is mounted, these props are ignored.
<Calendar selected-year="2009" selected-month="9"/>Sun
Mon
Tue
Wed
Thu
Fri
Sat
Time selection time: boolean | string
As a boolean, the time prop enables time selection controls. The selected time will be set to any selected date.
The time prop may also be a string of the form "HH:mm" that, apart from enabling time controls, sets the their intially selected time. If, however, there's an initially selected date, the initial time is ignored.
NOTE
When using the string model value modifier, dates are handled in the date-time form of the date time string format ("YYYY-MM-DDTHH:mm").
<Calendar time/>Sun
Mon
Tue
Wed
Thu
Fri
Sat
:
date.value === ''<Calendar time="01:17"/>Sun
Mon
Tue
Wed
Thu
Fri
Sat
:
date.value === ''Time format time-format: ('12' | '24') = '24'
<Calendar time time-format="12"/>Sun
Mon
Tue
Wed
Thu
Fri
Sat
:
date.value === ''NOTE
The time-format prop does not affect how
Time controls hours: TimeControls
minutes: TimeControls
The hours and minutes props are objects whose properties respectively configure time controls. The configuration objects have the following form
type TimeControls = {
min?: number;
max?: number;
step?: number;
}The min and max options define an inclusive range of values the corresponding time control can be set to. The step option becomes the step prop of the corresponding slider.
The following configuration objects are the default values for hours and minutes:
const defaultHours = { min: 0, max: 23, step: 1 }
const defaultMinutes = { min: 0, max: 59, step: 1 }<Calendar time
:hours="{
min: 10,
max: 22,
step: 2
}"
:minutes="{
min: 15,
max: 45,
step: 5
}"
/>Sun
Mon
Tue
Wed
Thu
Fri
Sat
:
Disabled dates disabled-dates: (CalendarDate | [CalendarDate, CalendarDate])[]
The disabled-dates prop is an array of dates or date ranges to be disabled. A date range is simply an array of two dates that define the inclusive limits of the range. Dates can be represented as a string of the form 'YYYY-MM-DD', a timestamp, or a date object.
<Calendar selected-year="2025" selected-month="1"
:disabled-dates="[
'2025-01-01',
new Date('2025-01-02T00:00'),
Date.parse('2025-01-03T00:00'),
['2025-01-13', '2025-01-17'],
[new Date('2025-01-20T00:00'), new Date('2025-01-24T00:00')],
[Date.parse('2025-01-27T00:00'), Date.parse('2025-01-31T00:00')],
]"
/>Sun
Mon
Tue
Wed
Thu
Fri
Sat
Enabled dates enabled-dates: (CalendarDate | [CalendarDate, CalendarDate])[]
The enabled-dates prop is an array of dates or date ranges to be enabled. This implies that when enabled-dates is set, all dates will be considered to be normally disabled. For this prop to take effect disabled-dates must be unset.
Similar to the disabled-dates prop, a date range is an array of two dates that define the inclusive limits of a range, and dates can be represented as a string of the form 'YYYY-MM-DD', a timestamp, or a date object.
<Calendar selected-year="2025" selected-month="1"
:enabled-dates="[
'2025-01-01',
new Date('2025-01-02T00:00'),
Date.parse('2025-01-03T00:00'),
['2025-01-13', '2025-01-17'],
[new Date('2025-01-20T00:00'), new Date('2025-01-24T00:00')],
[Date.parse('2025-01-27T00:00'), Date.parse('2025-01-31T00:00')],
]"
/>Sun
Mon
Tue
Wed
Thu
Fri
Sat
Disabled weekdays disabled-weekdays: number[]
The disabled-weekdays prop receives an array of weekday indexes. Calendar dates whose weekday index is in disabled-weekdays are disabled. Weekdays are considered to be indexed from Sunday through Saturday from 0 to 6
<Calendar :disabled-weekdays="[0,6]"/>Sun
Mon
Tue
Wed
Thu
Fri
Sat
Theme theme: theme = 'brand'
<Calendar theme="user"/>Sun
Mon
Tue
Wed
Thu
Fri
Sat
Size size: ('xs' | 'sm' | 'md' | 'lg' | 'xl') = 'md'
Sun
Mon
Tue
Wed
Thu
Fri
Sat
Sun
Mon
Tue
Wed
Thu
Fri
Sat
Sun
Mon
Tue
Wed
Thu
Fri
Sat
Sun
Mon
Tue
Wed
Thu
Fri
Sat
Sun
Mon
Tue
Wed
Thu
Fri
Sat
Radius radius: ('none' | 'sm' | 'md' | 'lg' | 'full') = 'md'
Sun
Mon
Tue
Wed
Thu
Fri
Sat
Sun
Mon
Tue
Wed
Thu
Fri
Sat
Sun
Mon
Tue
Wed
Thu
Fri
Sat
Sun
Mon
Tue
Wed
Thu
Fri
Sat
Sun
Mon
Tue
Wed
Thu
Fri
Sat
Disabled disabled: boolean
<Calendar disabled time time-format="12"/>Sun
Mon
Tue
Wed
Thu
Fri
Sat
:
Elements
| element | tag | description |
|---|---|---|
root | <div.calendar> | Calendar's root div container. |
dates | <div.calendar-dates> | Date button elements' wrapper |
Anatomy
<div.calendar/>
<div.calendar-head/>
<button.calendar-arrow.calendar-button/>
<Icon/>
<div.calendar-arrow.calendar-button/>
<button.calendar-button/>
<button.calendar-button/>
<button.calendar-arrow.calendar-button/>
<Icon/>
<div.calendar-body/>
<div.calendar-week/>
<p v-for="weekday of weekdays"/>
<div.calendar-dates/>
<label.calendar-date.calendar-button/>
<input/>
<div.calendar-months/>
<button.calendar-month.calendar-button/>
<div.calendar-years/>
<button.calendar-year.calendar-button/>
<div.calendar-foot/>
<div.calendar-time/>
<InputText/>
<p/>
<InputText/>
<Btn/>
<Slider/>
<Slider/>
API Reference
Props
| prop | type | default |
|---|---|---|
value | Date | null | string | number | Date[] | string[] | number[] | null |
locale | Intl.LocalesArgument | 'en' |
labels | Record<'month' | 'shortMonths' | 'shortWeekdays', string[]> | |
firstWeekday | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 0 |
min | string | number | Date | '1970-01-01' |
max | string | number | Date | '2131-12-31' |
selectedMonth | string | |
selectedYear | string | |
time | boolean | string | |
timeFormat | '24' | '12' | '24' |
hours | TimeControls | { min: 0, max: 23, step: 1 } |
minutes | TimeControls | { min: 0, max: 59, step: 1 } |
disabledDates | (CalendarDate | [CalendarDate, CalendarDate])[] | |
enabledDates | (CalendarDate | [CalendarDate, CalendarDate])[] | |
disabledWeekdays | (0 | 1 | 2 | 3 | 4 | 5 | 6)[] | |
disabled | boolean | |
descendant | boolean | |
theme | 'brand' | 'user' | 'ok' | 'info' | 'warn' | 'danger' | 'neutral' | 'brand' |
size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'md' |
radius | 'none' | 'sm' | 'md' | 'lg' | 'full' | 'md' |
spacing | '' | 'compact' | 'extended' | '' |
validator | Function | |
eagerValidation | boolean | |
elements | object | |
validationDelay | number | 300 |
validationCooldown | number | 350 |
Configuration options
Calendar's configuration options allow to overwrite some Calendar props' default values and may be overwritten under the calendar root-level configuration option.
calendar.<option> | type | default | global |
|---|---|---|---|
locale | Intl.LocalesArgument | 'en' | |
labels | Record<'month' | 'shortMonths' | 'shortWeekdays', string[]> | ||
firstWeekday | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 0 | |
timeFormat | '24' | '12' | '24' | |
validationDelay | number | ✅ | |
validationCooldown | number | ✅ | |
theme | theme | ✅ | |
size | size | ✅ | |
radius | radius | ✅ | |
spacing | spacing | ✅ |