Date Range Picker

SDateRangePicker picks a date range — a start and an end — with a single field and a pair of months in the calendar. Days in between are highlighted, the range ends are filled with the accent color. Like SDatePicker, it is built on SFormField and opens the calendar in a portal. The value is a { start, end } object with DateValue dates from @internationalized/date. Keep the value in a shallowRef, not a ref: a regular ref unwraps the date class, and type checking no longer recognizes it as a DateValue.

Basic usage

<script setup>
import { shallowRef } from 'vue'
import { parseDate } from '@internationalized/date'
const range = shallowRef({ start: parseDate('2026-07-11'), end: parseDate('2026-07-20') })
</script>

<template>
  <SDateRangePicker
    v-model="range"
    label="Booking period"
  />
</template>

Hint, error message, and date limits

<template>
  <SDateRangePicker
    label="Trip dates"
    hint="Future dates only"
    :min-value="min"
  />
  <SDateRangePicker
    label="Period"
    error="Select a range"
  />
</template>

Sizes

The size prop changes the field height: sm (28px), md (36px, the default), or lg (44px).

<template>
  <SDateRangePicker
    v-model="range"
    label="sm"
    size="sm"
  />
  <SDateRangePicker
    v-model="range"
    label="md"
    size="md"
  />
  <SDateRangePicker
    v-model="range"
    label="lg"
    size="lg"
  />
</template>

States

disabled locks the field and the calendar, readonly prevents changing the value, required adds * to the label, invalid marks the field as invalid without an error text.

<template>
  <SDateRangePicker
    v-model="range"
    label="Disabled"
    disabled
  />
  <SDateRangePicker
    v-model="range"
    label="Read-only"
    readonly
  />
  <SDateRangePicker
    v-model="empty"
    label="Required"
    required
  />
  <SDateRangePicker
    v-model="empty"
    label="Invalid"
    invalid
  />
</template>

Date limits

maxValue sets the upper bound of the range, and the isDateDisabled predicate disables arbitrary days (weekends in the example). Disabled days cannot be clicked in the calendar.

<script setup lang="ts">
import { shallowRef } from 'vue'
import { parseDate, getLocalTimeZone } from '@internationalized/date'

const empty = shallowRef()
const max = parseDate('2026-07-31')
const noWeekends = (value) => {
  const day = value.toDate(getLocalTimeZone()).getDay()
  return day === 0 || day === 6
}
</script>

<template>
  <SDateRangePicker
    v-model="empty"
    label="No later than end of July"
    :max-value="max"
  />
  <SDateRangePicker
    v-model="empty"
    label="Weekdays only"
    :is-date-disabled="noWeekends"
  />
</template>

Calendar settings

numberOfMonths sets how many months are shown at once (2 by default), weekStartsOn changes the first day of the week (1 is Monday), and fixedWeeks set to false turns off the stable 6-week grid height. The effect is visible with the calendar open.

<template>
  <SDateRangePicker
    v-model="empty"
    label="One month"
    :number-of-months="1"
  />
  <SDateRangePicker
    v-model="empty"
    label="Three months"
    :number-of-months="3"
  />
  <SDateRangePicker
    v-model="empty"
    label="Week starts on Monday"
    :week-starts-on="1"
    :fixed-weeks="false"
  />
</template>

prepend / append slots

The prepend and append slots add content inside the field frame, such as an icon or a button, next to the standard calendar trigger.

<template>
  <SDateRangePicker
    v-model="empty"
    label="With an icon"
  >
    <template #prepend>
      <SIcon
        icon="calendar"
        :size="16"
      />
    </template>
  </SDateRangePicker>

  <SDateRangePicker
    v-model="empty"
    label="With a button"
  >
    <template #append>
      <SButton
        size="sm"
        variant="ghost"
        icon="info"
        aria-label="Help"
      />
    </template>
  </SDateRangePicker>
</template>

Leaving the field

The field emits focus and blur events, like SInput. Moving between segments and into the calendar does not count as leaving the field — see the details and a validation example on the SDatePicker page.

API

Props

Name	Type	Default	Description
id	string	undefined	Field id. Generated automatically when not set (SSR-safe).
label	string	undefined	Field label.
hint	string	undefined	Hint below the field.
error	string	undefined	Error message. When set, the field is marked invalid.
size	"md" | "sm" | "lg"	"md"	Field size: sm (32px), md (40px) or lg (48px).
disabled	boolean	false	Disables the field and opening the calendar.
readonly	boolean	false	Read-only: the value cannot be changed.
required	boolean	false	Marks the field as required: draws * next to the label.
invalid	boolean	false	Explicitly marks the field invalid (in addition to error).
square	boolean	undefined	Square corners: removes the rounding of the field frame (rounded by default).
floating-label	boolean	true	Floating label: the label lives inside the frame, looks like a placeholder at rest and moves up to the top border on focus or when filled. On by default; false gives a regular label above the field. The label size is fixed and does not depend on size.
locale	string	undefined	Formatting locale (e.g. en-GB). By default it is derived from the library locale (ConfigProvider/installLocale, the locale option in Nuxt): en → en-US.
min-value	| CalendarDate | CalendarDateTime | ZonedDateTime	undefined	Minimum allowed date.
max-value	| CalendarDate | CalendarDateTime | ZonedDateTime	undefined	Maximum allowed date.
week-starts-on	0 | 1 | 2 | 3 | 4 | 5 | 6	undefined	First day of the week: 0 is Sunday, 1 is Monday, and so on.
fixed-weeks	boolean	true	Always show 6 weeks (stable grid height).
number-of-months	number	2	Number of months shown at once.
is-date-disabled	((date: CalendarDate | CalendarDateTime | ZonedDateTime) => boolean)	undefined	Predicate function: return true to disable a specific date.
open-calendar-label	string	undefined	Accessible name of the open-calendar button (defaults to the locale dictionary).
prev-month-label	string	undefined	Accessible name of the "previous month" button (defaults to the locale dictionary).
next-month-label	string	undefined	Accessible name of the "next month" button (defaults to the locale dictionary).
flat	boolean	undefined	Removes the shadow. Overridden by the elevation prop when it is set.
elevation	0 | 1 | 2 | 3 | 4 | 5	undefined	Shadow level 0–5 (scale); 0 means no shadow. Overrides flat.
model-value	{ start: | CalendarDate | CalendarDateTime | ZonedDateTime; end: | CalendarDate | CalendarDateTime | ZonedDateTime }	undefined	Selected range { start, end }. Two-way binding via v-model.

Events

Name	Signature	Description
update:modelValue	(value: SDateRange | undefined) => void	Emitted when modelValue changes. Used for two-way binding (v-model).
focus	(event: FocusEvent) => void	Focus entered the field. Moving between segments or into the calendar does not count.
blur	(event: FocusEvent) => void	Focus left the field. Moving between segments or into the calendar does not count.

Slots

Name	Description
prepend	Content at the start of the field, inside the frame (icon, button).
append	Content at the end of the field, inside the frame (icon, button).