import {Layout} from '../../src/Layout'; export default Layout;

import docs from 'docs:react-aria-components'; import vanillaDocs from 'docs:vanilla-starter/DateField'; import {DateField as VanillaDateField} from 'vanilla-starter/DateField'; import {DateField as TailwindDateField} from 'tailwind-starter/DateField'; import '../../tailwind/tailwind.css'; import Anatomy from '/packages/react-aria/docs/datepicker/datefield-anatomy.svg';

export const tags = ['calendar', 'input']; export const relatedPages = [{'title': 'useDateField', 'url': 'DateField/useDateField.html'}]; export const description = 'Allows users to enter and edit date and time values using a keyboard.';

DateField

<PageDescription>{docs.exports.DateField.description}</PageDescription>

Value

Use the value or defaultValue prop to set the date value, using objects in the @internationalized/date package. This library supports parsing date strings in multiple formats, manipulation across international calendar systems, time zones, etc.

tsx

"use client";
import {parseDate, getLocalTimeZone, type CalendarDate} from '@internationalized/date';
import {useDateFormatter} from 'react-aria';
import {DateField} from 'vanilla-starter/DateField';
import {useState} from 'react';

function Example() {
  let [date, setDate] = useState<CalendarDate | null>(parseDate('2020-02-03'));
  let formatter = useDateFormatter({ dateStyle: 'full' });

  return (
    <>
      <DateField
        ///- begin highlight -///
        value={date}
        onChange={setDate} />
      <p>Selected date: {date ? formatter.format(date.toDate(getLocalTimeZone())) : '--'}</p>
    </>
  );
}

Format options

The date format is automatically determined based on the user's locale. DateField supports several props to control how values are displayed.

tsx

"use client";
import {parseZonedDateTime} from '@internationalized/date';
import {DateField} from 'vanilla-starter/DateField';

<DateField
  /* PROPS */
  defaultValue={parseZonedDateTime('2025-02-03T08:45:00[America/Los_Angeles]')} />

International calendars

By default, DateField displays the value using the calendar system for the user's locale. Use <I18nProvider> to override the calendar system by setting the Unicode calendar locale extension. The onChange event always receives a date in the same calendar as the value or defaultValue (Gregorian if no value is provided), regardless of the displayed locale.

tsx

"use client";
import {I18nProvider} from 'react-aria-components';
import {parseZonedDateTime} from '@internationalized/date';
import {DateField} from 'vanilla-starter/DateField';

<I18nProvider/* PROPS */>
  <DateField defaultValue={parseZonedDateTime('2025-02-03T08:45:00[America/Los_Angeles]')} />
</I18nProvider>

Forms

Use the name prop to submit the selected date to the server as an ISO 8601 string. Set the isRequired, minValue, or maxValue props to validate the value, or implement custom client or server-side validation. See the Forms guide to learn more.

tsx

"use client";
import {today, getLocalTimeZone} from '@internationalized/date';
import {DateField} from 'vanilla-starter/DateField';
import {Button} from 'vanilla-starter/Button';
import {Form} from 'vanilla-starter/Form';;

<Form>
  <DateField
    label="Appointment date"
    ///- begin highlight -///
    name="date"
    isRequired
    minValue={today(getLocalTimeZone())}
    ///- end highlight -///
  />
  <Button type="submit">Submit</Button>
</Form>

API

tsx

<DateField>
  <Label />
  <DateInput>
    {segment => <DateSegment segment={segment} />}
  </DateInput>
  <Text slot="description" />
  <FieldError />
</DateField>

DateField

DateInput

DateSegment