Date Field

"use client"

import { CalendarDate } from "@internationalized/date"

The DateField component lets people type a date as locale-ordered segments. Use it for dates far from today, such as a date of birth or a document issue date, where typing eight digits is quicker than paging through years. Pick DatePicker instead when the date is close to today, such as a scheduled transfer, and a calendar helps.

Installation#

pnpmnpmyarnbun
pnpm dlx shadcn@latest add @dots/date-field
Copy

Usage#

Copyimport { CalendarDate } from "@internationalized/date"
 
import { DateField } from "@/components/ui/date-field"

Copy<DateField
  label="Date of birth"
  placeholderValue={new CalendarDate(1990, 1, 1)}
/>

Composition#

DateField builds the whole field. Use the parts to change the layout. The label, description and error come from DatePicker:

CopyDateFieldRoot
├── DatePickerLabel
├── DateFieldInput
├── DatePickerDescription
└── DatePickerError

Features#

• Day, month and year segments in the order of the current locale
• Arrow keys and typing to edit each segment
• minValue and maxValue with an error message
• A form name that submits the date as YYYY-MM-DD
• Everything React Aria DateField takes, including granularity for times
• An Input-shaped field or a compact pill

Locale#

The segment order follows the locale from React Aria I18nProvider. Without one it uses the browser locale.

"use client"

import { CalendarDate } from "@internationalized/date"

Invalid#

Set maxValue or minValue and an errorMessage. Use validationBehavior="aria" to show the error while the person types instead of on submit.

"use client"

import { CalendarDate } from "@internationalized/date"

Small#

Use size="sm" for a pill, for example a date filter in a toolbar. Pass aria-label when there is no visible label.

"use client"

import { CalendarDate } from "@internationalized/date"

Disabled#

Set isDisabled when the date can no longer be changed, such as a verified date of birth, and say why in the description.

"use client"

import { CalendarDate } from "@internationalized/date"

Composed#

Build the field from DateFieldRoot, DateFieldInput and the date picker label, description and error parts when you need a different layout.

"use client"

import { CalendarDate } from "@internationalized/date"

Server rendering#

With no value, defaultValue or placeholderValue, the empty segments are built from the current date, and without an I18nProvider the locale comes from the browser. Pass a placeholderValue and wrap the page in I18nProvider so the server and the client render the same field.

Copy<I18nProvider locale="en-US">
  <DateField
    label="Date of birth"
    placeholderValue={new CalendarDate(1990, 1, 1)}
  />
</I18nProvider>

Accessibility#

DateField is built on React Aria DateField. Each segment is a spin button that works with arrow keys, typing and screen readers, the group is labelled by the field label, and the description and error are linked to it.

• Pass a visible label. Without one, pass aria-label.
• Put format hints and limits in description, such as "You must be 18 or older", so they are read with the field.
• The error message is shown only when the field is invalid and is linked to the field, so it is read when the field gets focus. Keep the reason in the text, not in color alone.

API Reference#

DateField#

The whole field. Accepts all React Aria DateField props, such as value, defaultValue, onChange, placeholderValue, minValue, maxValue, granularity, name, isDisabled, isInvalid, isRequired and validationBehavior, except children and style.

DateFieldRoot#

The styled React Aria DateField root that lays out the label, input, help text and error. Accepts all React Aria DateField props.

DateFieldInput#

The day, month and year segments on an input fill, with no calendar button. Accepts React Aria DateInput props except children.