This section highlights common properties and general behavior shared by the calendar views. View-specific properties are discussed in their respective calendar sections and on the API pages.

Date format

model-value is how the date is set in QCalendar and is the user-selected date when there is an interactive calendar. This is the active date and can be used to move the calendar to a previous or next view (ie: day, week, month, etc). Typically, you set this with something like v-model="selectedDate". If your selectedDate contains a null, then the current date (today’s date) will be used.

QCalendar model values are Gregorian YYYY-MM-DD strings by default. When you pass calendar-system, date-bearing values for that component use the adapter-native YYYY-MM-DD calendar instead.

Now

If you do not set the now property, it will be set to the current date (today’s date). This property represents today, but it doesn’t have to be today.

Localization

Internally, QCalendar uses the browser’s Intl.DateTimeFormat for all localization. Therefore, QCalendar can only display the localization properly if it is supported by the user’s browser. If for some reason, it is not supported, then the fallback is to use American English (en-US). If you wanted to display French Canadian, you would use fr-CA, or Brazilian Portuguese pt-BR.

locale changes language and formatting. It does not change the calendar math by itself.

dir is the standard HTML direction attribute. QCalendar forwards it to the rendered view. Calendar adapters can provide default locale and direction values, and explicit locale or dir props override those defaults when your app needs a different presentation. If a slot mixes English or app data into an RTL calendar, isolate that content with dir="ltr" inside the slot.

Calendar systems

Use calendar-system when a view should use native calendar dates. This is an opt-in adapter object from the Timestamp packages such as @timestamp-js/calendar-islamic, @timestamp-js/calendar-saka, or @timestamp-js/calendar-persian.

<script setup>
import { ref } from 'vue'
import { islamicCivilCalendar } from '@timestamp-js/calendar-islamic'

const selectedDate = ref('1445-09-15')
</script>

<template>
  <q-calendar-month v-model="selectedDate" :calendar-system="islamicCivilCalendar" />
</template>

In this example, selectedDate is Hijri because the Islamic civil adapter is active. QCalendar also uses the adapter’s default locale, direction, and visible weekday order unless you pass locale, dir, or weekdays yourself. Date-bearing slots and mouse-event scopes receive adapter-native timestamps plus scope.calendarIdentity for Gregorian interop metadata such as gregorianDate and epochDay. See Calendar Adapters for week ranges, native month boundaries, RTL guidance, and adapter examples.

Dark and bordered

If you want a calendar to display dark mode, then set the dark property. If you want a calendar to have a border, then set the bordered property.

Weekdays

weekdays is a property that allows you to adjust the order of the days of the week. It is an array of numbers from 0 (Sunday) to 6 (Saturday). Gregorian calendars default to [0,1,2,3,4,5,6]; calendar adapters can provide their own default visible week order. If you wanted to have a 5 day work week, you would remove the Sunday and Saturday representations like this: [1,2,3,4,5]. If you wanted a calendar where Monday was the first day of the week, you would move Sunday to the end, like this: [1,2,3,4,5,6,0]. An explicit weekdays prop always overrides the adapter default.

Date type

The only three values accepted for the date-type property are round (default), rounded and square.

Alignment

The calendars all support header alignment in one way or another. There is another property, not displayed here and for interval-based calendars only, called date-header, that gives more control. You will have to look at the respective calendars to read about this property.

Weekday

The acceptable values are left, center (default) and right.

Date

The acceptable values are left, center (default) and right.

Active date

The active date is changed when the user clicks on a date or navigates using previous or next. In some edge cases, it is preferable not to show the active date (like when making a calendar date range selection).

Disabling days

Disabled days

This property is an Array of dates in the format YYYY-MM-DD. It also accepts ranges and object entries with optional color metadata for reservation-style disabled days.

Disabled before

This property is a date String in the format YYYY-MM-DD. Any date before this date, including the given date, will be disabled.

Disabled after

This property is a date String in the format YYYY-MM-DD. Any date after this date, including the given date, will be disabled.

Disabled weekdays

The disabled-weekdays property uses the same input as the weekdays property. Any value in the array will be disabled. Remember, 0=Sunday and 6=Saturday. So, to disable weekends, simply use [0,6].

No header

There may be some edge-cases where the header is not desirable. There is an example that shows how to build your own navigation with header information.

Use no-header to remove the full generated header. Use no-default-header-text or no-default-header-btn when you only want to replace part of the generated header with slots.

No scroll

All calendars try to take up 100% width and height. Either use styles to constrain a calendar or have a parent element (like a div) do it. In either case, the calendar will display it’s own scrollbar. Mostly so that headers are still visible. If you have an edge-case where this is not desirable, you can turn it off with the no-scroll property.

Accessibility

QCalendar generates ARIA attributes for supported calendar cells. Leave this enabled unless you are replacing the generated structure with your own accessibility layer through slots.

Labels

All labels in the calendars are formatted with the browsers internal Intl.DateTimeFormat function. This function allows you to specify a short format. For instance, Saturday becomes Sat. All calendars can automatically shrink label values. Some may first get an ellipsis, then short format and even smaller, if needed.

Short weekday label

Minimum label Length

As explained above, the calendars can format weekday labels smaller than the Intl.DateTimeFormat short format. The edge-case for this is to create a very small calendar picker. In this case, you could set the min-weekday-label to 1, in which case only the first character of the label will be used. This may not be desirable for some languages, as the weekdays may all have the same first character. In this case, set it to 2 or 3, whatever best suits the locale you are aiming for.

Label breakpoints

The weekday-breakpoints property is an array of two numbers. The parent div that contains the label knows it’s width. The array contains the values where you want label values to go from long format to short format automatically. The second value is when you want the values to start using extra short format based on the min-weekday-label property.

Transitions

Transitions are a way to make your calendar come alive for your end-user. When a calendar changes to a previous or next week/month, instead of just instantly displaying it, we can use the animated property to turn on transitions.

Then you can use the transition-prev and transition-next properties to change the default behavior, which is slide-right and slide-left, respectively.

See the QCalendar Transitions for more information.

Hoverable and focusable

The hoverable property allows each cell in a calendar to display a hovering effect. Sometimes this can be beneficial for the user as well as giving your calendar a bit of pizzaz. It comes with overhead, so it is optional.

The focusable property allows various cells within the calendar to have focus. This allows end-users to tab or shift-tab with navigation.

The use-navigation property turns on keyboard movement between supported cells. Use it with focusable when users should be able to move through dates, intervals, resources, or tasks with the keyboard.

The focus-type property works with the focusable property to determine what can have focus. This is an array of values. The values are: day, date, weekday, interval, and resource.

Selection

Selected dates

The selected-dates property is an array of dates in the form of YYYY-MM-DD.

Selected start and end dates

The property selected-start-end-dates takes an array of arrays. Each internal array contains a start and end date that is a selection. This allows you to have multiple selections if you wish.

Drag and drop

Drag enter

All functions receive a function signature of (e, type, scope). e is the actual event, type is a string, denoting where it came from. For instance, day, weekday, interval, etc. And, scope will be the data associated with this particular cell.

For all functions, you can return true or false. If true, this tells the calendar to add an additional droppable property into the scope. Then you can use day-class, interval-class or weekday-class to modify the CSS.

As an example:

onWeekdayClass ({ scope }) {
    return {
      droppable: scope.droppable === true
    }
  }

Then you can have CSS which defines your droppable class.

Slots and events

Slots and events look very similar to each other. Different slots have different data, but they all have the scope key in common.

Your slotted data will look like this:

{
  scope: {
    /* more data */
  }
}

Where an event will look like this:

{
  scope: { /* more data */ },
  event: { /* the event data */ }
}

You can always destructure the scope from the slotted data:

<q-calendar-day #day="{ scope }" />

If the scope has a timestamp within it and that’s all you need, then you can destructure even further:

<q-calendar-day #day="{ scope: { timestamp } }" />

When calendar-system is set, date-bearing slot and mouse-event scopes also include calendarTimestamp, calendarIdentity, and calendarSystem. The timestamp and calendarTimestamp values are native to the active adapter. Use calendarIdentity.gregorianDate when an external system still expects a Gregorian date, and calendarIdentity.epochDay when you need a neutral comparison key.

<q-calendar-day #day="{ scope: { timestamp, calendarTimestamp, calendarIdentity } }" />

Range-style events such as change expose adapter-aware range fields like calendarStart, calendarEnd, calendarDays, and calendarSystem.

The pattern here is to always be recognizable to the developer and to know what to expect.