Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Forms

DatePickerRange

A two-month range picker with continuous selection bands and native form values.

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

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add date-picker-range

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.

Vue
<script setup lang="ts">
import { ref } from 'vue'
import DatePickerRange from './components/ui/date-picker-range/DatePickerRange.vue'

const stay = ref<[string, string]>(['', ''])
</script>

<template>
  <label for="stay-dates">Stay dates</label>
  <DatePickerRange
    id="stay-dates"
    v-model="stay"
    start-name="checkIn"
    end-name="checkOut"
    min="2026-01-01"
    locale="en-GB"
    :messages="{
      calendarLabel: 'Choose check-in and check-out dates',
      previousMonth: 'Previous month',
      nextMonth: 'Next month',
      chooseDates: 'Choose dates',
      chooseEndDate: 'Choose end date',
      clearSelection: 'Clear dates',
    }"
  />
</template>

Two adjacent months make cross-month ranges visible at once. Narrow screens stack both months in a scrollable calendar. The first click starts a range and the second completes it; selected dates form continuous week-row bands. Set both name props to submit the two native values.

When to use it

Hotel stay

Collect check-in and check-out calendar dates as separate form values.

Report interval

Limit both endpoints to an allowed reporting window.

More examples

Hotel stay

Both name props are needed for native form submission.

Hotel stay
<script setup lang="ts">
import { ref } from 'vue'
import DatePickerRange from './components/ui/date-picker-range/DatePickerRange.vue'

const stay = ref<[string, string]>(['', ''])
const messages = {
  calendarLabel: 'Choose stay dates',
  previousMonth: 'Previous month',
  nextMonth: 'Next month',
  chooseDates: 'Choose dates',
  chooseEndDate: 'Choose check-out date',
  clearSelection: 'Clear dates',
}
</script>
<template>
  <label for="stay">Stay dates</label>
  <DatePickerRange
    id="stay"
    v-model="stay"
    start-name="checkIn"
    end-name="checkOut"
    locale="en-GB"
    :first-day-of-week="1"
    :messages="messages"
    required
  />
</template>

US reporting interval

Use Sunday-first layout where it matches the audience convention.

US reporting interval
<script setup lang="ts">
import { ref } from 'vue'
import DatePickerRange from './components/ui/date-picker-range/DatePickerRange.vue'

const interval = ref<[string, string]>(['', ''])
const messages = {
  calendarLabel: 'Choose reporting dates',
  previousMonth: 'Previous month',
  nextMonth: 'Next month',
  chooseDates: 'Choose dates',
  chooseEndDate: 'Choose end date',
  clearSelection: 'Clear dates',
}
</script>
<template>
  <label for="report-dates">Reporting dates</label>
  <DatePickerRange
    id="report-dates"
    v-model="interval"
    min="2026-01-01"
    max="2026-12-31"
    locale="en-US"
    :first-day-of-week="0"
    :messages="messages"
  />
</template>

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.

DatePickerRange

Complete API for DatePickerRange
NameType or signatureDefaultWhat it does
namepropstring | undefinedNot setName used when this control submits a value with a form.
referenceDatepropstring | undefinedNot setStable date used to decide which month or year appears first.
idpropstring | undefinedNot setGive the control an ID so a label or description can refer to it.
startNamepropstring | undefinedNot setForm field name used for the start of the range.
endNamepropstring | undefinedNot setForm field name used for the end of the range.
formpropstring | undefinedNot setAssociate the control with a form by its ID.
sizepropControlSize | undefined"md"Choose the visual size. Medium is the usual default where available.
invalidpropboolean | undefinedNot setShow the invalid state; also provide a visible error message.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
readonlypropboolean | undefinedNot setShow the value while preventing edits.
requiredpropboolean | undefinedNot setAsk the browser to require a value before form submission.
minpropstring | undefinedNot setSmallest allowed value.
maxpropstring | undefinedNot setLargest allowed value.
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.
messagespropDatePickerRangeMessagesRequiredSupply the text this component displays for its built-in actions and states.
modelValuemodelDatePickerRangeValue | undefined["", ""]Current value. Use v-model to keep it in sync with your page.
update:modelValueevent[value: DatePickerRangeValue]—Requests a new model value from the parent.
errorslot{ message: string; messages: string[]; }OptionalContent for the error area of DatePickerRange.
startElementexposedHTMLInputElement | null—Access start element from a component template ref.
endElementexposedHTMLInputElement | null—Access end element from a component template ref.
triggerElementexposedHTMLButtonElement | null—Access trigger element from a component template ref.
focusexposed() => void | undefined—Move keyboard focus to this control.
showPickerexposed() => void—Access show picker from a component template ref.
openexposed() => void—Open this component from application code.
closeexposed(restoreFocus?: boolean) => void—Close this component from application code.
Public type definitions
Public types
// packages/frameworks/vue/components/date-picker-range/types.ts
import type { ControlSize } from '@getweini/vue/types'

export type DatePickerRangeValue = [string, string]

export interface DatePickerRangeMessages {
  calendarLabel: string
  previousMonth: string
  nextMonth: string
  chooseDates: string
  chooseEndDate: string
  clearSelection: string
}

export interface DatePickerRangeProps {
  name?: string
  referenceDate?: string
  id?: string
  startName?: string
  endName?: string
  form?: string
  size?: ControlSize
  invalid?: boolean
  disabled?: boolean
  readonly?: boolean
  required?: boolean
  min?: string
  max?: string
  locale?: string
  firstDayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6
  messages: DatePickerRangeMessages
}


// packages/frameworks/vue/dist/types/index.d.ts
export type { ButtonOptions, ButtonProps } from './button';
export type ControlSize = 'sm' | 'md' | 'lg';
export interface SelectOption<T = unknown> {
    label: string;
    value: T;
    disabled?: boolean;
}
/** Application-owned copy. Bind translated strings reactively when the locale changes. */
export interface ListboxMessages {
    /** Popup name when no aria-label or aria-labelledby is supplied. */
    listboxLabel: string;
    empty: string;
    clearSelection: string;
}
export interface ListboxProps<T> {
    options: readonly SelectOption<T>[];
    messages: ListboxMessages;
    id?: string;
    disabled?: boolean;
    required?: boolean;
    invalid?: boolean;
    name?: string;
    form?: string;
    placeholder?: string;
    size?: ControlSize;
    clearable?: boolean;
    gap?: number;
    /** Supply stable equality for object values. Values must be unique. */
    by?: (a: T, b: T) => boolean;
    /** Required for meaningful form submission of object values. */
    serialize?: (value: T) => string;
}


// packages/frameworks/vue/dist/types/button.d.ts
import type { Component } from 'vue';
/** Options shared by button implementations across frameworks. */
export interface ButtonOptions<Variant extends string = string, Size extends string = string> {
    variant?: Variant;
    size?: Size;
    disabled?: boolean;
    loading?: boolean;
    type?: 'button' | 'submit' | 'reset';
}
/** Vue-specific target options extend the reusable button contract. */
export interface ButtonProps<Variant extends string = 'default' | 'secondary' | 'outline' | 'ghost' | 'destructive', Size extends string = 'sm' | 'md' | 'lg'> extends ButtonOptions<Variant, Size> {
    as?: 'button' | 'a' | Component;
    asChild?: boolean;
}

Implementation notes

  • The model is a [start, end] tuple of YYYY-MM-DD strings; the end is empty while the user is choosing.
  • Dates are local calendar dates. Resolve check-in and check-out times in the property’s IANA timezone in your booking logic.

Accessibility and localization

  • Supply an associated label and translate calendar, navigation, and selection messages.

Source contract and editing guidance