Date Picker

SDatePicker combines a segmented date input (SDateField) with a popover calendar (SCalendar): the date can be typed on the keyboard or picked with the mouse. It is built on SFormField (label, hint, error message), the navigation uses SIcon. The value is a DateValue from @internationalized/date. The calendar opens in a portal, so the demos are wrapped in <ClientOnly>. 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 date = shallowRef(parseDate('2026-07-11'))
</script>

<template>
  <SDatePicker
    v-model="date"
    label="Delivery date"
  />
</template>

Hint, error message, and date limits

<template>
  <SDatePicker
    label="Visit date"
    hint="Today or later"
    :min-value="min"
  />
  <SDatePicker
    label="Date"
    error="This field is required"
  />
</template>

Sizes

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

<template>
  <SDatePicker
    v-model="date"
    label="sm"
    size="sm"
  />
  <SDatePicker
    v-model="date"
    label="md"
    size="md"
  />
  <SDatePicker
    v-model="date"
    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>
  <SDatePicker
    v-model="date"
    label="Disabled"
    disabled
  />
  <SDatePicker
    v-model="date"
    label="Read-only"
    readonly
  />
  <SDatePicker
    v-model="empty"
    label="Required"
    required
  />
  <SDatePicker
    v-model="empty"
    label="Invalid"
    invalid
  />
</template>

Date limits

maxValue sets the upper bound of the selection, 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>
  <SDatePicker
    v-model="empty"
    label="No later than end of July"
    :max-value="max"
  />
  <SDatePicker
    v-model="empty"
    label="Weekdays only"
    :is-date-disabled="noWeekends"
  />
</template>

Calendar settings

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>
  <SDatePicker
    v-model="empty"
    label="Week starts on Monday"
    :week-starts-on="1"
  />
  <SDatePicker
    v-model="empty"
    label="No fixed 6 weeks"
    :fixed-weeks="false"
  />
</template>

Leaving the field

Like SInput, the field emits focus and blur events, for example to validate the value once the user leaves the field. Moving between segments and into the calendar does not count as leaving: blur fires when focus has left both the field and the open calendar. SDateRangePicker, SDateField, and STimeField emit the same events.

<script setup>
import { ref, shallowRef } from 'vue'

const pickup = shallowRef()
const error = ref()

function validate() {
  error.value = pickup.value ? undefined : 'Enter a pickup date'
}
</script>

<template>
  <SDatePicker
    v-model="pickup"
    label="Pickup date"
    required
    :error="error"
    @blur="validate"
  />
</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>
  <SDatePicker
    v-model="empty"
    label="With an icon"
  >
    <template #prepend>
      <SIcon
        icon="calendar"
        :size="16"
      />
    </template>
  </SDatePicker>

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

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).
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	| CalendarDate | CalendarDateTime | ZonedDateTime	undefined	Selected date (DateValue). Two-way binding via v-model.

Events

Name	Signature	Description
update:modelValue	( value: | CalendarDate | CalendarDateTime | ZonedDateTime | 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).