Date Field

PreviousNext

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

Docs API Reference
Event date
mmddyyyy
Select a date for your event.
import { DateField } from "@/components/ui/date-field"

export function DateFieldDemo() {
  return (
    <DateField label="Event date" description="Select a date for your event." />
  )
}

Installation

pnpm dlx shadcn@latest add date-field

Usage

import { DateField } from "@/components/ui/date-field"
<DateField
  label="Event date"
  description="Select a date for your event."
/>

About

The DateField component is built on top of React Aria Components and uses the @internationalized/date library for date manipulation.

Examples

Default

Event date
mmddyyyy
Select a date for your event.
import { DateField } from "@/components/ui/date-field"

export function DateFieldDemo() {
  return (
    <DateField label="Event date" description="Select a date for your event." />
  )
}

<DateField
  label="Event date"
  description="Select a date for your event."
/>

Disabled

Event date
mmddyyyy
This field is disabled.
import { DateField } from "@/components/ui/date-field"

export function DateFieldDisabled() {
  return (
    <DateField
      label="Event date"
      description="This field is disabled."
      isDisabled
    />
  )
}

<DateField
  label="Event date"
  description="This field is disabled."
  isDisabled
/>

Validation

Birth date
mmddyyyy
Enter your birth date.
"use client"

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

export function DateFieldValidation() {
  return (
    <DateField
      label="Birth date"
      description="Enter your birth date."
      isRequired
      errorMessage="Please enter a valid date."
    />
  )
}

<DateField
  label="Birth date"
  description="Enter your birth date."
  isRequired
  errorMessage="Please enter a valid date."
/>

Controlled

Appointment date
1152024
Select your appointment date.

Selected date: 2024-01-15

"use client"

import { useState } from "react"
import { parseDate } from "@internationalized/date"

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

export function DateFieldControlled() {
  const [value, setValue] = useState(parseDate("2024-01-15"))

  return (
    <div className="space-y-4">
      <DateField
        label="Appointment date"
        description="Select your appointment date."
        value={value}
        onChange={setValue}
      />
      <p className="text-muted-foreground text-sm">
        Selected date: {value ? value.toString() : "None"}
      </p>
    </div>
  )
}

"use client"
 
import { useState } from "react"
import { parseDate } from "@internationalized/date"
 
import { DateField } from "@/components/ui/date-field"
 
export default function DateFieldControlled() {
  const [value, setValue] = useState(parseDate("2024-01-15"))
 
  return (
    <div className="space-y-4">
      <DateField
        label="Appointment date"
        description="Select your appointment date."
        value={value}
        onChange={setValue}
      />
      <p className="text-sm text-muted-foreground">
        Selected date: {value ? value.toString() : "None"}
      </p>
    </div>
  )
}

Min and Max Values

Meeting date
mmddyyyy
Select a date within the next 7 days.
"use client"

import { getLocalTimeZone, today } from "@internationalized/date"

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

export function DateFieldMinMax() {
  const now = today(getLocalTimeZone())

  return (
    <DateField
      label="Meeting date"
      description="Select a date within the next 7 days."
      minValue={now}
      maxValue={now.add({ days: 7 })}
    />
  )
}

"use client"
 
import { today, getLocalTimeZone } from "@internationalized/date"
 
import { DateField } from "@/components/ui/date-field"
 
export default function DateFieldMinMax() {
  const now = today(getLocalTimeZone())
 
  return (
    <DateField
      label="Meeting date"
      description="Select a date within the next 7 days."
      minValue={now}
      maxValue={now.add({ days: 7 })}
    />
  )
}

Granularity

Date only
mmddyyyy
Year, month, and day.
Month and year
mmyyyy
Month and year only.
import { DateField } from "@/components/ui/date-field"

export function DateFieldGranularity() {
  return (
    <div className="space-y-4">
      <DateField
        label="Date only"
        description="Year, month, and day."
        granularity="day"
      />
      <DateField
        label="Month and year"
        description="Month and year only."
        granularity="month"
      />
    </div>
  )
}

<div className="space-y-4">
  <DateField
    label="Date only"
    description="Year, month, and day."
    granularity="day"
  />
  <DateField
    label="Month and year"
    description="Month and year only."
    granularity="month"
  />
</div>

API Reference

DateField

PropTypeDefaultDescription
labelstring-Label text for the date field
descriptionstring-Help text displayed below the input
errorMessagestring | ((validation: ValidationResult) => string)-Error message for validation
valueDateValue-The current value (controlled)
defaultValueDateValue-The default value (uncontrolled)
onChange(value: DateValue) => void-Handler called when the value changes
minValueDateValue-The minimum allowed date
maxValueDateValue-The maximum allowed date
granularity"day" | "hour" | "minute" | "second""day"Determines the smallest unit editable
isDisabledbooleanfalseWhether the date field is disabled
isReadOnlybooleanfalseWhether the date field is read-only
isRequiredbooleanfalseWhether the date field is required
placeholderValueDateValue-A placeholder date that controls the default values of segments

See the React Aria DateField documentation for more props and detailed information.

Internationalization

The DateField component automatically formats dates based on the user's locale. The @internationalized/date library handles calendar systems and localization.

import { parseDate } from "@internationalized/date"
 
// ISO 8601 format
const date = parseDate("2024-12-25")

Calendar Systems

The date field supports multiple calendar systems through the @internationalized/date library:

  • Gregorian
  • Buddhist
  • Hebrew
  • Indian
  • Islamic (Hijri)
  • Japanese
  • Persian
  • Taiwan

See the @internationalized/date documentation for more information.

Related Components

  • Calendar - For visual date selection
  • Date Picker - Combines a date field with a calendar popover
  • Field - For composing accessible form fields