Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Forms

Calendar

An inline keyboard-accessible single-date or date-range calendar.

Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.

Interactive showcase

October 2026

Install

Run in your project
bunx --bun @getweini/cli@latest add calendar

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

October 2026

October 2026

Vue
<script setup lang="ts">
import { ref } from 'vue'
import Calendar from './components/ui/calendar/Calendar.vue'

const date = ref('2026-10-12')
const range = ref<[string, string]>(['2026-10-12', '2026-10-16'])
const messages = { previousMonth: 'Previous month', nextMonth: 'Next month' }
</script>
<template>
  <Calendar v-model="date" :messages="messages" />
  <Calendar v-model="range" mode="range" :messages="messages" />
</template>

Arrow keys move by day or week; Home/End jump to week edges and Page Up/Down change months. Range mode uses the same continuous selection band as DatePickerRange and emits an empty end until the second date is selected.

When to use it

Inline date selection

Keep a date grid visible when choosing a date is the main task.

Availability range

Let users choose start and end dates directly in a page without opening a popover.

More examples

US and French week layouts

Locale changes labels; firstDayOfWeek separately controls the week grid.

US and French week layouts
<script setup lang="ts">
import { ref } from 'vue'
import Calendar from './components/ui/calendar/Calendar.vue'

const usDate = ref('2026-10-12')
const frenchDate = ref('2026-10-12')
const english = { previousMonth: 'Previous month', nextMonth: 'Next month' }
const french = { previousMonth: 'Mois précédent', nextMonth: 'Mois suivant' }
</script>
<template>
  <section aria-label="US event date">
    <Calendar v-model="usDate" locale="en-US" :first-day-of-week="0" :messages="english" />
  </section>
  <section aria-label="Date de l’événement">
    <Calendar v-model="frenchDate" locale="fr-FR" :first-day-of-week="1" :messages="french" />
  </section>
</template>

Inline availability range

The second tuple entry stays empty until the end date is chosen.

Inline availability range
<script setup lang="ts">
import { ref } from 'vue'
import Calendar from './components/ui/calendar/Calendar.vue'

const range = ref<[string, string]>(['', ''])
const messages = { previousMonth: 'Previous month', nextMonth: 'Next month' }
</script>
<template>
  <section aria-label="Available dates">
    <Calendar
      v-model="range"
      mode="range"
      min="2026-10-01"
      max="2026-12-31"
      locale="en-GB"
      :first-day-of-week="1"
      :messages="messages"
    />
  </section>
  <p v-if="range[0]">Start:{{ range[0] }}; end:{{ range[1] || 'choose an end date' }}</p>
</template>

Date and timezone for scheduling

Keep the chosen local date and IANA zone separate; an existing instant can be displayed in that zone with Intl.

Date and timezone for scheduling
<script setup lang="ts">
import { computed, ref } from 'vue'
import Calendar from './components/ui/calendar/Calendar.vue'

const localDate = ref('2026-10-12')
const timeZone = ref('Europe/Luxembourg')
const existingInstant = ref('2026-10-12T13:00:00Z')
const messages = { previousMonth: 'Previous month', nextMonth: 'Next month' }
const existingLocalTime = computed(() =>
  new Intl.DateTimeFormat('en-GB', {
    dateStyle: 'medium',
    timeStyle: 'short',
    timeZone: timeZone.value,
  }).format(new Date(existingInstant.value)),
)
const schedulingInput = computed(() => ({ localDate: localDate.value, timeZone: timeZone.value }))
</script>
<template>
  <section aria-label="Meeting date">
    <Calendar v-model="localDate" locale="en-GB" :first-day-of-week="1" :messages="messages" />
  </section>
  <p>Chosen date:&nbsp;{{ schedulingInput.localDate }} in&nbsp;{{ schedulingInput.timeZone }}</p>
  <p>Existing appointment in that zone:&nbsp;{{ existingLocalTime }}</p>
</template>

Locale and time zones

These calendars share one selected YYYY-MM-DD date. Locale changes the displayed month and day names; firstDayOfWeek changes the grid. The underlying date value remains the same. Calendar renders Gregorian dates; setting a locale does not switch calendar systems.

United States · en-US

October 2026

France · fr-FR

octobre 2026

Japan · ja-JP

2026年10月

Selected date: 2026-10-12

One instant in three time zones

An event at 2026-10-12T23:30:00Z lands on different local dates. Calendar does not convert instants; choose and store an IANA time zone in your application when scheduling events. This demonstration compares America/New_York, Europe/Luxembourg, and Asia/Tokyo using Intl.DateTimeFormat.

America/New_York
Mon, Oct 12, 2026, 7:30 PM EDT
Europe/Luxembourg
Tue, Oct 13, 2026, 1:30 AM GMT+2
Asia/Tokyo
Tue, Oct 13, 2026, 8:30 AM GMT+9

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

Calendar

Complete API for Calendar
NameType or signatureDefaultWhat it does
referenceDatepropstring | undefinedNot setSerialized civil date shared by server and client for deterministic initial rendering.
modeprop"single" | "range" | undefined"single"Choose the selection or display mode.
minpropstring | undefinedNot setSmallest allowed value.
maxpropstring | undefinedNot setLargest allowed value.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
readonlypropboolean | undefinedNot setShow the value while preventing edits.
localepropstring | undefinedNot setChoose the language and regional formatting for dates or text.
firstDayOfWeekprop0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined1Choose which weekday begins each calendar row.
messagespropCalendarMessagesRequiredSupply the text this component displays for its built-in actions and states.
modelValuemodelCalendarValue | undefinedNot setCurrent value. Use v-model to keep it in sync with your page.
update:modelValueevent[value: CalendarValue | undefined]—Requests a new model value from the parent.
elementexposedHTMLElement | null—Reference to the underlying HTML element.
focusexposed() => void | undefined—Move keyboard focus to this control.
Public type definitions
Public types
// packages/frameworks/vue/components/calendar/types.ts
export type CalendarRange = [start: string, end: string]
export type CalendarValue = string | CalendarRange

export interface CalendarMessages {
  previousMonth: string
  nextMonth: string
}

export interface CalendarProps {
  /** Serialized civil date shared by server and client for deterministic initial rendering. */
  referenceDate?: string
  mode?: 'single' | 'range'
  min?: string
  max?: string
  disabled?: boolean
  readonly?: boolean
  locale?: string
  firstDayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6
  messages: CalendarMessages
}

Implementation notes

  • Calendar stores Gregorian YYYY-MM-DD dates, not timezone-aware instants or dates in another calendar system. Locale affects month/day labels, while firstDayOfWeek sets the grid order.
  • To create an instant from a chosen local date, combine it with a wall-clock time and IANA timezone in your application or backend and resolve daylight-saving gaps or overlaps. Intl formats an existing instant in a zone; it does not turn a date-only Calendar value into an instant.

Accessibility and localization

  • Give each inline calendar a surrounding accessible name and translate previous/next month messages. The roving day button supports arrows, Home/End, and Page Up/Down.

Source contract and editing guidance