Black Friday: 50% off all products for the first 50 customers. Only 10 left. Use code
40/50 claimed
See pricing →
November 14, 2026

Quasar Date Picker: Ranges, Masks and Popups

The Quasar date picker in practice: model masks vs input masks, a date field with QPopupProxy, date ranges in one input, disabled days and time zones.
Quasar
Vue
Forms
Dates

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.

How the Quasar date picker stores dates

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:

  • Values you set must match the mask. With 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.
  • A string has no time zone. That's a feature, and the last section explains why.

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.

Model mask vs input mask

There are two different props called mask, and they do different things:

q-date maskq-input mask
ControlsThe format of the model stringWhich characters the user can type, and where
SyntaxDate tokens: YYYY, MM, DD, ddd…Placeholders: # for a digit, plus named masks
Examplemask="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.

A date field with QInput and QPopupProxy

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:

  • Both masks describe the same format. The input accepts typed dates as 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.
  • Any styled input works. The popup lives in the #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.
  • Closing on pick. @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.

Quasar date range in one input

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:

  1. A one-day range is a string. Click the same day twice and q-date emits '2026/11/14', not { from, to }. The reason is 'add-day' instead of 'add-range'.
  2. A { 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.

Disable days with options

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.

Time zones: keep dates as strings

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:

  • Keep calendar dates as strings end to end: in the model, in your API, in a date column in the database.
  • When you need a 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.
  • Compute "today" in the browser if it decides what users can pick. On the server, "today" is the server's date, which can differ from the user's around midnight.

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.

Common questions about the Quasar date picker

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.

Next step

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.