Date Field
Edit a date with keyboard segments or a calendar.
Printed on the invoice and used to calculate the due date.
Installation
pnpm dlx shadcn@4.18.0 add @siteplane/date-fieldComplete the one-time setup first. Registry JSON lists source files and dependencies.
For this page’s examples, also install:
pnpm dlx shadcn@4.18.0 add @siteplane/button @siteplane/form @siteplane/inputField is installed with Input.
Usage
import { DateField } from "@/siteplane/components/date-field";
<DateField aria-label="Meeting date" />;Controlled value
Pass value and onValueChange to keep the date in React state. onValueChange receives undefined when the field is cleared; store null for an empty controlled value, because undefined makes the field uncontrolled.
Unavailable dates
Use calendarProps.disabled to block past dates and weekends. The calendar doesn't offer these dates, and a typed date that breaks a rule marks the field invalid once it loses focus or the form is submitted; FieldError shows the message. Check the date again on the server.
We deliver Monday to Friday.
Disabled, read-only and invalid
A disabled Field also disables the date field, and readOnly shows a date that can't be changed on the regular field surface. For an error from your application, set invalid on Field and explain the problem in a FieldError.
Set by your workspace admin.
Submission and reset
With name, DateField submits a hidden YYYY-MM-DD string; the example submits { "startDate": "2026-10-05" }. Changing locale changes only the display, and an empty field submits an empty string. With required, submitting an empty field is blocked, the field is focused and FieldError shows the required message. Native form reset restores defaultValue; reset controlled state yourself.
Decorative icon
Use iconMode="decorative-start" for dates people usually type, such as a date of birth. The icon is decorative and no calendar opens; iconMode="none" removes the icon.
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
aria-label | string | unset | Accessible name when no FieldLabel or aria-labelledby names the field. |
aria-labelledby / aria-describedby | string | unset | External label and help ids; inside a Field, FieldLabel, FieldDescription and FieldError are connected automatically. |
aria-invalid | AriaAttributes[aria-invalid] | unset | External invalid state; while set, it replaces the built-in date checks. |
value / default | Date | null (value only) | uncontrolled / unset | Controlled or initial date; null is an empty controlled value. |
on | (value: Date | undefined) => void | unset | Reports a completed date, or undefined when cleared. |
disabled | boolean | false | Prevents editing/opening; a disabled Field also disables the field. |
class | string | segment width | Outer control styling and width. By default the field is as wide as its segments and the calendar button; a width utility such as w-full or w-64 replaces that. |
locale | string | context | Formatting locale, not time zone. |
calendar | CalendarOptions | unset | The calendar options below: defaultMonth, disabled, startMonth, endMonth and todayDate. |
read | boolean | false | Read-only field on the regular surface; required blocks form submission while empty, focuses the field and shows the required message in FieldError. |
size | sm | md | lg | xl | provider / lg | Control size. |
text | sm | base | unset | Field text size; unset is 14px, or 16px at xl, like Input. |
variant | default | elevated | inset | soft | default | Input surface. |
form | string | unset | Associated form ID. |
name | string | unset | Hidden serialized input name; a Field name takes precedence. |
icon | action-end | decorative-start | none | action-end | Calendar button, decorative leading icon or no icon. |
open | string | Open date calendar | Calendar button name. |
incomplete | string | Enter a complete date. | The error of a required field while its date is incomplete, shown by FieldError. |
profile | default | input-group | default | input-group renders only the date segments, without surface, calendar button or popover, for use inside your own InputGroup. |
inset | boolean | false | Only with profile input-group: adds space before the day segment. |
size and variant use the same scale and surfaces as Input; see Input sizes and variants.
Calendar options
calendarProps takes CalendarOptions, the type of the same options on Calendar. startMonth and endMonth (Date, unset) limit the calendar to the first and last allowed months. disabled (unset) makes days unavailable with one matcher or a list of matchers, each a Date, a (date: Date) => boolean test or a rule with after, before, from, to and dayOfWeek (0 Sunday through 6 Saturday); true disables the whole calendar. Both apply to picking in the calendar and to typed dates.
defaultMonth (Date, unset) sets the month the calendar shows when it opens; while it is set, it also wins over the month of the selected date. todayDate (Date, the device's date) sets the day the calendar marks as today; without a selected date, the calendar opens on its month, and typed segments start from it.
Exported types: DateFieldProps. These describe the contracts above.
Usage notes
Values use native Date calendar fields in the local runtime time zone. Locale changes formatting, not the zone. The field is compact by default, as wide as a date takes; add className="w-full" to fill a form column. Inside a Field, FieldLabel names DateField and clicking it focuses the first segment; outside a Field, pass aria-label or aria-labelledby. Arrow keys change the focused segment. Only the props listed above are supported, and DateField renders its own segments, calendar button and popover; it accepts no children or ref.
The segments read in the direction of the locale, which the arrow keys between them follow too, and are isolated from the text around them. An en-US date stays 10/14/2026 in a right-to-left page, while the field keeps the page's direction: its calendar button sits at the page's inline end.