Components
Dates
Date Field

Date Field

A date field allows users to enter and edit date and time values using a keyboard.

Aria docs Aria API Reference Report an issue Edit this page

default.tsx

<DateField />

Installation

Install the following dependencies:

npm install react-aria-components

Copy and paste the following code into your project.

date-field.tsx

field.tsx

date-input.tsx

input.tsx

"use client";

import * as React from "react";
import {
  DateField as AriaDateField,
  type DateFieldProps as AriaDateFieldProps,
  type DateValue,
} from "react-aria-components";
import { tv, type VariantProps } from "tailwind-variants";
import { DateInput, DateSegment } from "./date-input";
import { Field, type FieldProps } from "./field";
import { InputRoot, type InputRootProps, type inputStyles } from "./input";

const dateFieldStyles = tv({
  slots: {
    root: "flex flex-col items-start gap-2",
  },
});

interface DateFieldProps<T extends DateValue>
  extends DateFieldRootProps<T>,
    Omit<FieldProps, "children">,
    VariantProps<typeof inputStyles> {
  prefix?: React.ReactNode;
  suffix?: React.ReactNode;
  isLoading?: boolean;
  loaderPosition?: "prefix" | "suffix";
}

const DateField = <T extends DateValue>({
  className,
  size,
  label,
  description,
  errorMessage,
  prefix,
  suffix,
  isLoading,
  loaderPosition = "suffix",
  isRequired,
  isDisabled,
  necessityIndicator,
  contextualHelp,
  ...props
}: DateFieldProps<T>) => {
  return (
    <DateFieldRoot
      className={className}
      isRequired={isRequired}
      isDisabled={isLoading || isDisabled}
      {...props}
    >
      <Field
        label={label}
        description={description}
        errorMessage={errorMessage}
        isRequired={isRequired}
        necessityIndicator={necessityIndicator}
        contextualHelp={contextualHelp}
      >
        <DateFieldInput
          size={size}
          prefix={prefix}
          suffix={suffix}
          isLoading={isLoading}
          loaderPosition={loaderPosition}
        />
      </Field>
    </DateFieldRoot>
  );
};

interface DateFieldRootProps<T extends DateValue> extends Omit<AriaDateFieldProps<T>, "className"> {
  className?: string;
}
const DateFieldRoot = <T extends DateValue>({ className, ...props }: DateFieldRootProps<T>) => {
  const { root } = dateFieldStyles();
  return <AriaDateField className={root({ className })} {...props} />;
};

const DateFieldInput = (props: InputRootProps) => (
  <InputRoot {...props}>
    <DateInput>{(segment) => <DateSegment segment={segment} />}</DateInput>
  </InputRoot>
);

export type { DateFieldProps, DateFieldRootProps };
export { DateField, DateFieldRoot };

Update the import paths to match your project setup.

Usage

Use a DateField to allow users to enter and edit time values using a keyboard.

Options

Label

A visual label can be provided for the DateField using the label prop or a hidden label using aria-label prop.

label.tsx

<DateField label="Meeting date" />
<DateField aria-label="Meeting date" />

Sizes

Use the size prop to control the size of the DateField.
The default variant is "md".

sizes.tsx

<DateField size="sm" />
<DateField size="md" />
<DateField size="lg" />

Prefix and suffix

To add additional context for the DateField, such as an icon, use the prefix and suffix props.

prefix-and-suffix.tsx

<DateField prefix={<CalendarIcon />} />
<DateField suffix={<CalendarIcon />} />

Description

A description can be supplied to DateField via the description prop. The description is always visible unless the isInvalid prop is true and an error message is provided.

description.tsx

<DateField label="Appointment" description="Please select a date." />

Contextual help

A ContextualHelp element may be placed next to the label to provide additional information or help about a DateField.

contextual-help.tsx

<DateField
  label="Appointment"
  contextualHelp={<ContextualHelp />}
/>

Error message

An errorMessage can be supplied to DateField, which will be displayed when the isInvalid prop is set to true.

error-message.tsx

<DateField
  label="Meeting"
  isInvalid
  errorMessage="Meetings can't be scheduled in the past."
/>

Time zones

DateField is time zone aware when a ZonedDateTime object is provided as the value.

time-zones.tsx

<DateField defaultValue={parseAbsoluteToLocal("2021-11-07T07:45:00Z")} />

Granularity

The granularity prop allows you to control the smallest unit that is displayed by DateField.

granularity.tsx

<DateField
  label="Hour"
  granularity="hour"
  defaultValue={parseAbsoluteToLocal("2021-04-07T18:45:22Z")}
/>
<DateField
  label="Minute"
  granularity="minute"
  defaultValue={parseAbsoluteToLocal("2021-04-07T18:45:22Z")}
/>
<DateField
  label="Second"
  granularity="second"
  defaultValue={parseAbsoluteToLocal("2021-04-07T18:45:22Z")}
/>

Placeholder value

Use the placeholderValue prop to control the default values of each segment. The default value is midnight.

placeholder.tsx

<DateField label="Meeting date" placeholderValue={new CalendarDate(1980, 1, 1)} />

Hide time zone

Use the hideTimeZone prop to hide the time zone abbreviation.

hide-time-zone.tsx

<DateField
  label="Appointment time"
  granularity="minute"
  defaultValue={parseZonedDateTime("2022-11-07T10:45[America/Los_Angeles]")}
  hideTimeZone
/>

Hour cycle

Use the hourCycle prop to control the hour cycle of the DateField.

hour-cycle.tsx

<DateField granularity="minute" hourCycle={24} />

Loading

Use the isLoading prop to control the loading state of the DateField. Use the loaderPosition prop to control the position of the loader.

loading.tsx

<DateField aria-label="Meeting date" isLoading loaderPosition="prefix" />
<DateField aria-label="Meeting date" isLoading loaderPosition="suffix" />

Disabled

Use the isDisabled prop to disable the DateField.

disabled.tsx

<DateField label="Event date" isDisabled />

ReadOnly

The isReadOnly boolean prop makes the DateField's text content immutable. Unlike isDisabled, the DateField remains focusable and the contents can still be copied.

read-only.tsx

<DateField label="Event date" value={new CalendarDate(1980, 1, 1)} isReadOnly />

Required

Use the isRequired prop to mark the DateField as required. Use the necessityIndicator prop to control the visual style of the required state.

required.tsx

<DateField label="Event date" isRequired />
<DateField label="Event date" isRequired necessityIndicator="icon" />
<DateField label="Event date" isRequired necessityIndicator="label" />
<DateField label="Event date" necessityIndicator="label" />

Uncontrolled

An initial, uncontrolled value can be provided to the DateField using the defaultValue prop.

uncontrolled.tsx

<DateField defaultValue={parseDate("2020-02-03")} />

Controlled

Use the value and onChange props to control the value of the input.

controlled.tsx

const [value, setValue] = React.useState(parseDate("2020-02-03"));
  return <DateField value={value} onChange={setValue} />

Composition

If you need to customize things further, you can drop down to the composition level.

composition.tsx

"use client";

import React from "react";
import { DateFieldRoot } from "@/lib/components/core/default/date-field";
import { DateInput, DateSegment } from "@/lib/components/core/default/date-input";
import { Description, Label } from "@/lib/components/core/default/field";
import { InputRoot } from "@/lib/components/core/default/input";

function Demo() {
  return (
    <DateFieldRoot>
      <Label>Meeting time</Label>
      <InputRoot>
        <DateInput>{(segment) => <DateSegment segment={segment} />}</DateInput>
      </InputRoot>
      <Description>Please select a time between 9 AM and 5 PM.</Description>
    </DateFieldRoot>
  );
}

API Reference

Prop	Type	Default	Description
minValue	DateValue	-	The minimum allowed date that a user may select.
maxValue	DateValue	-	The maximum allowed date that a user may select.
isDateUnavailable	(date: DateValue) => boolean	-	Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
placeholderValue	DateValue	-	A placeholder date that influences the format of the placeholder shown when no value is selected. Defaults to 12:00 AM or 00:00 depending on the hour cycle.
hourCycle	12 \| 24	-	Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale.
granularity	'hour' \| 'minute' \| 'second'	-	Determines the smallest unit that is displayed in the date picker. By default, this is "day" for dates, and "minute" for times.
hideTimeZone	boolean	false	Whether to hide the time zone abbreviation.
shouldForceLeadingZeros	boolean	-	Whether to always show leading zeros in the hour field. By default, this is determined by the user's locale.
isDisabled	boolean	-	Whether the input is disabled.
isReadOnly	boolean	-	Whether the input can be selected but not changed by the user.
isRequired	boolean	-	Whether user input is required on the input before form submission.
isInvalid	boolean	-	Whether the input value is invalid.
validate	(value: MappedDateValue<DateValue>) => ValidationError \| true \| null \| undefined	-	A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.
autoFocus	boolean	-	Whether the element should receive focus on render.
isOpen	boolean	-	Whether the input value is invalid.
defaultOpen	boolean	-	Whether the input value is invalid.
value	DateValue \| null	-	The current value (controlled).
defaultValue	DateValue \| null	-	The default value (uncontrolled).
name	string	-	The name of the input element, used when submitting an HTML form.
validationBehavior	'native' \| 'aria'	'aria'	Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
children	ReactNode \| (values: DateFieldRenderProps & {defaultChildren: ReactNode \| undefined}) => ReactNode	-	The children of the component. A function may be provided to alter the children based on component state.
className	string	-	The CSS className for the element.
style	CSSProperties \| (values: DateFieldRenderProps & {defaultStyle: CSSProperties}) => CSSProperties	-	The inline style for the element. A function may be provided to compute the style based on component state.

Event	Type	Description
onFocus	(e: FocusEvent<Target>) => void	Handler that is called when the element receives focus.
onBlur	(e: FocusEvent<Target>) => void	Handler that is called when the element loses focus.
onFocusChange	(isFocused: boolean) => void	Handler that is called when the element's focus status changes.
onKeyDown	(e: KeyboardEvent) => void	Handler that is called when a key is pressed.
onKeyUp	(e: KeyboardEvent) => void	Handler that is called when a key is released.
onOpenChange	(isOpen: boolean) => void	Handler that is called when the overlay's open state changes.
onChange	(value: MappedDateValue<DateValue>) => void	Handler that is called when the value changes.

Data attribute	Description
[data-invalid]	Whether the date field is invalid.
[data-disabled]	Whether the date field is disabled.

Accessibility

Keyboard interactions

Key	Description
Tab	Places focus on the first segment. If a segment is already in focus, moves focus to the next segment. If last segment in in focus, moves focus to the next element in the page tab sequence.
ArrowRight ArrowLeft	Moves focus between segments.
ArrowUp ArrowDown	Increments/decrements the value of the segment.