DatePicker

A date picker combines a DateField and a Calendar popover to allow users to enter or select a date and time value.

Theme 
Date
 
granularity 
isDisabled 
Example
DatePicker.tsx
DatePicker.css
import {DatePicker} from './DatePicker';

<DatePicker label="Date" />

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.

Selected date: Monday, February 3, 2020

import {parseDate, getLocalTimeZone, type CalendarDate} from '@internationalized/date';
import {useDateFormatter} from 'react-aria';
import {DatePicker} from './DatePicker';
import {useState} from 'react';

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

  return (
    <>
      <DatePicker
        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. DatePicker supports several props to control how values are displayed.

Date
granularity 
hourCycle 
hideTimeZone 
shouldForceLeadingZeros 
import {parseZonedDateTime} from '@internationalized/date';
import {DatePicker} from './DatePicker';

<DatePicker
  label="Date"
  defaultValue={parseZonedDateTime('2025-02-03T08:45:00[America/Los_Angeles]')} />

International calendars

By default, DatePicker 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.

Locale
Calendar
import {I18nProvider} from 'react-aria-components';
import {parseZonedDateTime} from '@internationalized/date';
import {DatePicker} from './DatePicker';

<I18nProvider locale="hi-IN-u-ca-indian">
  <DatePicker 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. The isDateUnavailable callback prevents certain dates from being selected. See the Forms guide to learn more.

Appointment date
import {isWeekend, today, getLocalTimeZone} from '@internationalized/date';
import {useLocale} from 'react-aria-components';
import {DatePicker} from './DatePicker';
import {Button} from './Button';
import {Form} from './Form';;

function Example() {
  let {locale} = useLocale();
  let now = today(getLocalTimeZone());
  let disabledRanges = [
    [now, now.add({ days: 5 })],
    [now.add({ days: 14 }), now.add({ days: 16 })],
    [now.add({ days: 23 }), now.add({ days: 24 })]
  ];

  return (
    <Form>
      <DatePicker
        label="Appointment date"
        name="date"
        isRequired
        minValue={today(getLocalTimeZone())}
        isDateUnavailable={date => (
          isWeekend(date, locale) ||
          disabledRanges.some((interval) =>
            date.compare(interval[0]) >= 0 && date.compare(interval[1]) <= 0
          )
        )}
      />
      <Button type="submit">Submit</Button>
    </Form>
  );
}

API

Event date9 / 17 / 2021GroupLabelButtonFieldSeptember 2021SMTWTF5789101314151619202122232412326272930628S11182541217CalendarPopover
<DatePicker>
  <Label />
  <Group>
    <DateInput />
    <Button />
  </Group>
  <Text slot="description" />
  <FieldError />
  <Popover>
    <Calendar />
  </Popover>
</DatePicker>

DatePicker

NameTypeDefault
pageBehaviorDefault: visible
Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
firstDayOfWeek'sun''mon''tue''wed''thu''fri''sat'Default:
The day that starts the week.
isDateUnavailable(date: ) => booleanDefault:
Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
placeholderValuenullDefault:
A placeholder date that influences the format of the placeholder shown when no value is selected. Defaults to today's date at midnight.
hourCycle1224Default:
Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale.
granularityDefault:
Determines the smallest unit that is displayed in the date picker. By default, this is "day" for dates, and "minute" for times.
hideTimeZonebooleanDefault: false
Whether to hide the time zone abbreviation.
shouldForceLeadingZerosbooleanDefault:
Whether to always show leading zeros in the month, day, and hour fields. By default, this is determined by the user's locale.
isDisabledbooleanDefault:
Whether the input is disabled.
isReadOnlybooleanDefault:
Whether the input can be selected but not changed by the user.
children<>Default:
The children of the component. A function may be provided to alter the children based on component state.
valuenullDefault:
The current value (controlled).
defaultValuenullDefault:
The default value (uncontrolled).
onChange(value: <>null) => voidDefault:
Handler that is called when the value changes.

Default className: react-aria-DatePicker

Render PropCSS Selector
isFocusWithinCSS Selector: [data-focus-within]
Whether an element within the date picker is focused, either via a mouse or keyboard.
isFocusVisibleCSS Selector: [data-focus-visible]
Whether an element within the date picker is keyboard focused.
isDisabledCSS Selector: [data-disabled]
Whether the date picker is disabled.
isReadOnlyCSS Selector: [data-readonly]
Whether the date picker is read only.
isInvalidCSS Selector: [data-invalid]
Whether the date picker is invalid.
isOpenCSS Selector: [data-open]
Whether the date picker's popover is currently open.
stateCSS Selector:
State of the date picker.