@saper-vedere/date-range-picker

@saper-vedere/date-range-picker

A Vue 3 + TypeScript date range picker. Two-month calendar view, click-to-select, drag-to-adjust, optional input mode with popover, presets, theming via CSS custom properties, and full slot customisation.

• Vue 3.4+ (peer dependency, externalised from the bundle)
• TypeScript types included
• Single CSS file — no runtime style injection
• ESM + CJS builds

Install

npm install @saper-vedere/date-range-picker
# or
yarn add @saper-vedere/date-range-picker
# or
pnpm add @saper-vedere/date-range-picker

Vue 3 must be installed in the host application.

Quick start

<script setup lang="ts">
import { ref } from 'vue'
import { DateRangePicker } from '@saper-vedere/date-range-picker'
import '@saper-vedere/date-range-picker/style.css'

const start = ref<Date>()
const end = ref<Date>()
</script>

<template>
  <DateRangePicker v-model:start="start" v-model:end="end" />
</template>

start and end are independent v-models so you can bind only one if needed.

Modes

Inline (default)

Renders the two-calendar grid directly in place.

<DateRangePicker v-model:start="start" v-model:end="end" mode="inline" />

Input

Renders a masked text input that opens the calendar in a popover when focused. Typing into the input parses partial dates as you go; pressing Enter commits and closes.

<DateRangePicker
  v-model:start="start"
  v-model:end="end"
  mode="input"
  input-format="dd/MM/yyyy"
  input-separator=" - "
/>

Format tokens supported: dd, MM, yyyy.

Props

Theming

The library declares its design tokens as CSS custom properties on the root element with :where(.drp-@saper-vedere/date-range-picker) (zero specificity), so any of the following mechanisms work:

1. Pass a partial theme object — applied as inline CSS variables, takes precedence:

<DateRangePicker
  v-model:start="start"
  v-model:end="end"
  :theme="{ accent: '#2563eb', bg: '#f8fafc', text: '#0f172a' }"
/>

2. Override via stylesheet — load after style.css:

.drp-@saper-vedere/date-range-picker {
  --drp-accent: #2563eb;
  --drp-bg: #f8fafc;
}

Available tokens (see DateRangePickerTheme):

The full default theme is exported as defaultTheme for inspection.

Localisation

Two independent channels:

• Locale-formatted content (month names, weekday abbreviations) — set the locale prop.
• Static UI labels (action buttons, nav arrow aria-labels) — pass messages.

<DateRangePicker
  v-model:start="start"
  v-model:end="end"
  locale="en-US"
  :messages="{
    commit: 'Apply',
    reset: 'Reset',
    viewSelection: 'View selection',
    prevMonth: 'Previous month',
    nextMonth: 'Next month',
  }"
/>

Defaults are French (see defaultMessages exported from the package). All keys are optional — provide only the ones you want to override.

Presets

Render one-click range shortcuts alongside the calendar. Each preset's getRange() is called on click; the picker enters the selected state with that range and reframes the calendars onto it (the user still confirms via the action bar, or you can wire mode="input" so committing closes the popover).

import type { DateRangePickerPresets } from '@saper-vedere/date-range-picker'

const presets: DateRangePickerPresets = [
  // First group
  [
    { title: 'Last 7 days', getRange: () => ({ start: ..., end: ... }) },
    { title: 'Last 30 days', getRange: () => ({ start: ..., end: ... }) },
  ],
  // Second group, separated by a divider
  [
    { title: 'This month', getRange: () => ({ start: ..., end: ... }) },
    { title: 'This year', getRange: () => ({ start: ..., end: ... }) },
  ],
]

A flat array (no nesting) is also accepted and rendered as a single group.

Slots

Custom input example

<DateRangePicker v-model:start="start" v-model:end="end" mode="input">
  <template #input="{ value, onValueChange, onFocus, onBlur, onKeydown, attrs }">
    <input
      :value="value"
      @input="onValueChange(($event.target as HTMLInputElement).value)"
      @focus="onFocus"
      @blur="onBlur"
      @keydown="onKeydown"
      v-bind="attrs"
    />
  </template>
</DateRangePicker>

Public API

import {
  DateRangePicker,
  Button,
  defaultMessages,
  defaultTheme,
  themeToCssVars,
  type DateRangePickerProps,
  type DateRangePickerMode,
  type DateRangePickerMessages,
  type DateRangePickerTheme,
  type DateRangePickerPreset,
  type DateRangePickerPresets,
  type DateRangeInputSlotBindings,
  type PickerState,
  type YearMonth,
  type DayInfo,
  type MonthGrid,
} from '@saper-vedere/date-range-picker'

Development

yarn dev         # local demo at /src/App.vue
yarn build       # build the library to dist/
yarn typecheck   # vue-tsc
yarn test        # vitest run

License

MIT