Preview

Installation

npx sigma-ui@latest add date-field

Usage

<script setup lang="ts">
import { ref } from 'vue';
import { type DateValue } from '@internationalized/date';
import { DateField } from '@/components/ui/date-field';

const value = ref<DateValue>();
</script>

<template>
  <DateField v-model="value" />
</template>

• v-model is an @internationalized/date DateValue. CalendarDate gives day segments, and CalendarDateTime or ZonedDateTime add time segments. granularity picks the smallest segment (day by default, or hour, minute, second), and hourCycle switches between a 12-hour and a 24-hour clock.
• minValue and maxValue limit the range. A value outside it sets data-invalid on the field, and the field shows the destructive border.
• The field renders each segment in a DateFieldInput. Pass your own default slot to render the segments yourself, for example to add an icon.
• Give the field an id and point a label at it with for. Clicking the label focuses the first segment.

Related

• Time Field
• Date Picker, when the date is picked from a calendar

Examples

With label

Granularity and hour cycle

Min and max

Disabled

Invalid

Form

API Reference

DateField

Props

Prop	Type	Default
defaultValue The default value for the calendar	DateValue	-
defaultPlaceholder The default placeholder date	DateValue	-
placeholder The placeholder date, which is used to determine what month to display when no date is selected. This updates as the user navigates the calendar and can be used to programmatically control the calendar view	DateValue	-
modelValue The controlled value of the field. Can be bound as v-model.	DateValue | null	-
hourCycle The hour cycle used for formatting times. Defaults to the local preference	HourCycle	-
step The stepping interval for the time fields. Defaults to 1.	DateStep	-
stepSnapping Whether to enforce snapping the time value to the nearest step increment after input. Defaults to false.	boolean	-
granularity The granularity to use for formatting times. Defaults to day if a CalendarDate is provided, otherwise defaults to minute. The field will render segments for each part of the date up to and including the specified granularity	Granularity	-
hideTimeZone Whether or not to hide the time zone segment of the field	boolean	-
maxValue The maximum date that can be selected	DateValue	-
minValue The minimum date that can be selected	DateValue	-
locale The locale to use for formatting dates	string	-
disabled Whether or not the date field is disabled	boolean	-
readonly Whether or not the date field is readonly	boolean	-
isDateUnavailable A function that returns whether or not a date is unavailable	Matcher	-
id Id of the element	string	-
dir The reading direction of the date field when applicable. <br> If omitted, inherits globally from ConfigProvider or assumes LTR (left-to-right) reading mode.	Direction	-
asChild Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.	boolean	-
as The element or component this component should render as. Can be overwritten by asChild.	AsTag | Component	"div"
name The name of the field. Submitted with its owning form as part of a name/value pair.	string	-
required When true, indicates that the user must set the value before the owning form can be submitted.	boolean	-

Events

Event	Payload
update:modelValue Event handler called whenever the model value changes	[date: DateValue]
update:placeholder Event handler called whenever the placeholder value changes	[date: DateValue]

Slots

Slot	Scope
default The date segments. Each one renders in a DateFieldInput unless you pass your own content.	{ modelValue: DateValue | null; segments: { part: SegmentPart; value: string; }[]; isInvalid: boolean; }

DateFieldInput

Props

Prop	Type	Default
partrequired The part of the date to render	SegmentPart	-
asChild Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.	boolean	-
as The element or component this component should render as. Can be overwritten by asChild.	AsTag | Component	"div"

Slots

Slot	Scope
default The content of the component.	-

Accessibility

The field is a group of spin buttons, one for each segment (month, day, and year). Typing a number fills the focused segment and moves to the next one.

Key	Description
ArrowUp or ArrowDown	Increases or decreases the focused segment.
ArrowLeft or ArrowRight	Moves to the previous or next segment.
Backspace	Deletes the last digit of the focused segment.
Tab	Moves to the next segment, then out of the field.