Date Field

SDateField is a segmented date input: separate editable parts (month, day, year) instead of free text. This rules out ambiguous formats and parsing errors, works from the keyboard (arrows increment, typing digits fills the segment), and is localized. The value is a DateValue from @internationalized/date; the field is built on SFormField (label, hint, error message).

Value and shallowRef

Keep the date in a shallowRef, not a ref. A regular ref unwraps the value through UnwrapRef: the CalendarDate class is turned into a structural type, the private field is lost, and vue-tsc no longer recognizes it as a DateValue — TS2322: Type '{ readonly calendar: … }' is not assignable to type 'DateValue'. Narrowing the ref itself (ref<CalendarDate>) does not help: it is unwrapped anyway. shallowRef stores the value as is, and a date does not need deep reactivity anyway, since it is replaced as a whole.

Basic usage

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

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

Empty field, hint, and error message

<template>
  <SDateField
    label="Date of birth"
    hint="Format MM/DD/YYYY"
  />
  <SDateField
    label="Date"
    error="Enter a valid date"
  />
</template>

States

disabled locks the field, readonly prevents changing the segments, invalid marks the field as invalid (red border), required adds * to the label.

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

Sizes

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

<template>
  <SDateField
    v-model="date"
    label="sm"
    size="sm"
  />
  <SDateField
    v-model="date"
    label="md"
    size="md"
  />
  <SDateField
    v-model="date"
    label="lg"
    size="lg"
  />
</template>

Granularity

granularity sets the smallest editable segment. The default is day for a date; for a value with time (CalendarDateTime) you can go down to minute or second.

<script setup lang="ts">
import { shallowRef } from 'vue'
import { parseDateTime } from '@internationalized/date'
const dateTime = shallowRef(parseDateTime('2026-07-11T14:30'))
</script>

<template>
  <SDateField
    v-model="dateTime"
    label="To the minute"
    granularity="minute"
  />
  <SDateField
    v-model="dateTime"
    label="To the second"
    granularity="second"
  />
</template>

prepend / append slots

The prepend and append slots insert content inside the field frame, for example a calendar icon.

<template>
  <SDateField
    v-model="date"
    label="Leading icon"
  >
    <template #prepend>
      <SIcon
        icon="calendar"
        :size="16"
      />
    </template>
  </SDateField>

  <SDateField
    v-model="date"
    label="Trailing icon"
  >
    <template #append>
      <SIcon
        icon="calendar"
        :size="16"
      />
    </template>
  </SDateField>
</template>

Leaving the field

The field emits focus and blur events, like SInput. Moving between segments 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.
floating-label	boolean	true	Floating label: the label sits inside the border, looks like a placeholder at rest and floats up to the top edge on focus or when filled. On by default; false renders a regular label above the field. The label size is fixed and does not depend on size.
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 input and makes the field inactive.
readonly	boolean	false	Read-only: the segments cannot be changed.
required	boolean	false	Marks the field as required: adds * to the label.
invalid	boolean	false	Explicitly marks the field invalid (in addition to error).
square	boolean	undefined	Square corners: removes the field border radius (rounded by default).
locale	string	undefined	Formatting locale (for example en-GB). Derived from the library locale by default (ConfigProvider/installLocale, in Nuxt the locale option): en → en-US.
granularity	| "day" | "hour" | "minute" | "second"	undefined	Granularity: the smallest segment to display (day/hour/minute/second). Defaults to day for CalendarDate and minute for dates with time.
min-value	| CalendarDate | CalendarDateTime | ZonedDateTime	undefined	Minimum allowed date.
max-value	| CalendarDate | CalendarDateTime | ZonedDateTime	undefined	Maximum allowed date.
model-value	| CalendarDate | CalendarDateTime | ZonedDateTime	undefined	Field value (DateValue from @internationalized/date). Two-way bound 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 does not count.
blur	(event: FocusEvent) => void	Focus left the field. Moving between segments does not count.

Slots

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