The Quasar date picker, q-date, is a calendar that writes the picked date into a string. Most of the trouble with it comes from that string: which format it's in, how it gets into an input, what a range looks like, and what happens when someone turns it into a JavaScript Date. This post goes through those in order: masks, the q-input + q-popup-proxy pattern, ranges in one input, disabling days, and time zones. All behavior is checked against Quasar 2.35.2, including a few range details that only show up in the source.
q-date works with strings, not Date objects. The model is formatted with the mask prop, which defaults to YYYY/MM/DD:
<q-date v-model="day" mask="YYYY-MM-DD" />With that mask, picking November 14 sets day to '2026-11-14'. Three rules follow from it:
mask="YYYY-MM-DD", assigning '2026/11/14' won't select anything. Write '2026-11-14'.options and events always use YYYY/MM/DD, whatever your mask is. The strings passed to those functions, and the arrays you give them, use slashes.The mask can include time tokens, so a q-date and a q-time can share one model, for example mask="YYYY-MM-DD HH:mm" on both. The Quasar docs warn against the timestamp tokens x and X with server rendering: decoding them depends on the time zone, so server and browser can render different days and hydration fails.
There are two different props called mask, and they do different things:
q-date mask | q-input mask | |
|---|---|---|
| Controls | The format of the model string | Which characters the user can type, and where |
| Syntax | Date tokens: YYYY, MM, DD, ddd… | Placeholders: # for a digit, plus named masks |
| Example | mask="DD/MM/YYYY" | mask="##/##/####" |
q-input has a named mask date, which is ####/##/##, and a built-in 'date' rule that checks for YYYY/MM/DD. They only match q-date's default format. For any other format, write the input mask yourself and use your own rule:
import { date } from 'quasar'
const isValidDate = (value: string) =>
!Number.isNaN(date.extractDate(value, 'DD/MM/YYYY').getTime()) || 'Use DD/MM/YYYY'date.extractDate returns an invalid Date for impossible dates such as 31/02/2026, which a regular expression would accept.
The standard pattern puts the calendar in a popup that opens from an icon in the input:
<script setup lang="ts">
import { ref } from 'vue'
import { date, type QPopupProxy } from 'quasar'
const dueDate = ref('')
const popup = ref<QPopupProxy | null>(null)
const isValidDate = (value: string) =>
!Number.isNaN(date.extractDate(value, 'DD/MM/YYYY').getTime()) || 'Use DD/MM/YYYY'
function onPicked(_value: string | null, reason: string) {
if (reason === 'add-day') popup.value?.hide()
}
</script>
<template>
<q-input
v-model="dueDate"
label="Due date"
outlined
mask="##/##/####"
placeholder="DD/MM/YYYY"
:rules="[isValidDate]"
>
<template #append>
<q-icon name="event" class="cursor-pointer" aria-label="Open calendar">
<q-popup-proxy ref="popup" cover transition-show="scale" transition-hide="scale">
<q-date v-model="dueDate" mask="DD/MM/YYYY" @update:model-value="onPicked" />
</q-popup-proxy>
</q-icon>
</template>
</q-input>
</template>What each piece does:
DD/MM/YYYY, and the calendar reads and writes the same string. Typing and picking stay in sync because they share one model.q-popup-proxy picks a menu or a dialog. On a window wider and taller than its breakpoint (450px by default; the smaller of width and height counts), it renders a q-menu next to the icon. Below it, it renders a q-dialog, which is easier to use on a phone. The input stays focused while the popup is open.#append slot, so you can add it to any q-input, including the 20 designs in the Inputs Block (3 of them Free). None of those is a date picker, but each takes this slot as is.@update:model-value receives a reason as its second argument. 'add-day' means the user clicked a day, so the popup closes. The Quasar docs instead put a Close button in the default slot of q-date with v-close-popup. That's better when users browse months before picking, or when a q-time follows.Add range and the model becomes an object:
{ from: '2026/11/14', to: '2026/11/20' }Two behaviors in 2.35.2 that will bite you if you only read the docs:
q-date emits '2026/11/14', not { from, to }. The reason is 'add-day' instead of 'add-range'.{ from, to } with the same date on both sides is ignored. q-date only shows ranges where from comes before to. So if you normalize a one-day pick to { from: x, to: x }, you have to turn it back into a string before handing it to q-date, or the selection disappears.Clicking a day inside a selected range removes the range (unless you set no-unset). The @range-start and @range-end events tell you when the user starts and finishes picking.
Here's a range field that handles both cases and keeps one shape, { from, to }, for the rest of your code:
<script setup lang="ts">
import { computed, ref } from 'vue'
import type { QPopupProxy } from 'quasar'
interface DateRange {
from: string
to: string
}
const range = ref<DateRange | null>(null)
const popup = ref<QPopupProxy | null>(null)
const pickerModel = computed(() =>
range.value && range.value.from === range.value.to ? range.value.from : range.value,
)
const label = computed(() => {
if (!range.value) return ''
const { from, to } = range.value
return from === to ? from : `${from} – ${to}`
})
function onPicked(value: DateRange | string | null, reason: string) {
range.value = typeof value === 'string' ? { from: value, to: value } : value
if (reason === 'add-range' || reason === 'add-day') popup.value?.hide()
}
</script>
<template>
<q-input :model-value="label" label="Stay" outlined readonly>
<template #append>
<q-icon name="date_range" class="cursor-pointer" aria-label="Pick dates">
<q-popup-proxy ref="popup" cover>
<q-date :model-value="pickerModel" range mask="YYYY-MM-DD" @update:model-value="onPicked" />
</q-popup-proxy>
</q-icon>
</template>
</q-input>
</template>The input is readonly because typing a range by hand is error-prone. Picking in the calendar is the only way in. If people do need to type, use two inputs, one for each end, each with its own popup. That's also the question in today's poll: one range picker, or two pickers?
For several ranges in one model, combine range with multiple. The model becomes an array that can mix single days and { from, to } objects.
The options prop decides which days can be picked. Give it an array of YYYY/MM/DD strings, or a function that receives each day as YYYY/MM/DD and returns true if it's allowed:
import { date } from 'quasar'
const today = date.formatDate(Date.now(), 'YYYY/MM/DD')
function isBookable(day: string) {
const weekday = date.extractDate(day, 'YYYY/MM/DD').getDay()
return day >= today && weekday !== 0 && weekday !== 6
}<q-date v-model="appointment" :options="isBookable" />Comparing the strings works because YYYY/MM/DD sorts the same way as the dates. Define the function in your script instead of inline in the template, as the API docs recommend, so it isn't recreated on every render.
To limit the months a user can browse, add navigation-min-year-month and navigation-max-year-month (both YYYY/MM). They only limit navigation, not the model.
With range, options is only partly enforced. The disabled days can't start or end a range, but a range can still span them: pick a Friday and the next Monday, and the weekend is inside the range. If that matters (hotel nights, leave requests), check the range in onPicked and reject or split it.
A date with no time ("the invoice is due on November 14") is not a moment in time, and it shouldn't become one. The usual bug:
new Date('2026-11-14')JavaScript parses a date-only ISO string as midnight UTC. For anyone west of Greenwich, that's still November 13 in local time, and the UI shows the wrong day.
The safe approach:
date column in the database.Date, for example to get the weekday, parse it with date.extractDate(value, mask). It builds the date from its parts in local time, so it stays on the right day.Only real moments, like "the order was placed at 14:32", need time zones. Store those as UTC timestamps and format them for the viewer. The details of formatting and parsing are a topic of their own; this post stops at keeping the picker honest.
Why doesn't my q-date show the value I set? The string doesn't match the mask. With the default mask the value must look like 2026/11/14.
Why do I get a string instead of { from, to } with range? The user picked a one-day range. Normalize it in your handler, as above.
How do I use q-date without a popup? Drop it on the page with v-model. Add minimal to hide the header, or landscape to put it on the side.
Is it keyboard accessible? Since 2.25, the days are one Tab stop: arrow keys move between days, Home and End jump to the start or end of the week, and Page Up and Page Down change the month. Each day is announced with its full date.
For a whole form rather than one field, the Form Layouts Block has four complete form cards built with Quasar, one of them Free. Its invoice form (a Paid Component) uses the pattern from this post for the invoice and due dates: a q-input with a q-popup-proxy and a q-date with mask="YYYY-MM-DD", next to customer, item, quantity and tax fields.