Sections

Get Started

Forms

Date Range Picker

A date range picker combines two date fields with a range calendar to allow users to select a date range.

Trip dates

mmddyyyy

Select your trip start and end dates.

import { DateRangePicker } from "@/components/ui/date-range-picker"

export function DateRangePickerDemo() {
  return (
    <DateRangePicker
      label="Trip dates"
      description="Select your trip start and end dates."
    />
  )
}

Installation

CLI

Manual


pnpm
npm
yarn
bun
pnpm dlx shadcn@latest add date-range-picker

Usage

import { DateRangePicker } from "@/components/ui/date-range-picker"

<DateRangePicker
  label="Trip dates"
  description="Select your trip start and end dates."
/>

About

The DateRangePicker component is built on top of React Aria Components and combines two Date Field components with a Range Calendar in a popover. It allows users to select a date range by either typing dates or selecting them from a calendar.

Examples

Default

Trip dates

mmddyyyy

Select your trip start and end dates.

import { DateRangePicker } from "@/components/ui/date-range-picker"

export function DateRangePickerDemo() {
  return (
    <DateRangePicker
      label="Trip dates"
      description="Select your trip start and end dates."
    />
  )
}

<DateRangePicker
  label="Trip dates"
  description="Select your trip start and end dates."
/>

Disabled

Trip dates

mmddyyyy

This field is disabled.

import { DateRangePicker } from "@/components/ui/date-range-picker"

export function DateRangePickerDisabled() {
  return (
    <DateRangePicker
      label="Trip dates"
      description="This field is disabled."
      isDisabled
    />
  )
}

<DateRangePicker
  label="Trip dates"
  description="This field is disabled."
  isDisabled
/>

Validation

Vacation dates

mmddyyyy

Select your vacation start and end dates.

"use client"

import { DateRangePicker } from "@/components/ui/date-range-picker"

export function DateRangePickerValidation() {
  return (
    <DateRangePicker
      label="Vacation dates"
      description="Select your vacation start and end dates."
      isRequired
      errorMessage="Please select a valid date range."
    />
  )
}

<DateRangePicker
  label="Vacation dates"
  description="Select your vacation start and end dates."
  isRequired
  errorMessage="Please select a valid date range."
/>

Controlled

Hotel reservation

12202024

12272024

Select your check-in and check-out dates.

Selected range: 2024-12-20 to 2024-12-27

"use client"

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

import { DateRangePicker } from "@/components/ui/date-range-picker"

export function DateRangePickerControlled() {
  const [value, setValue] = useState({
    start: parseDate("2024-12-20"),
    end: parseDate("2024-12-27"),
  })

  return (
    <div className="space-y-4">
      <DateRangePicker
        label="Hotel reservation"
        description="Select your check-in and check-out dates."
        value={value}
        onChange={setValue}
      />
      <p className="text-muted-foreground text-sm">
        Selected range: {value.start.toString()} to {value.end.toString()}
      </p>
    </div>
  )
}

"use client"
 
import { useState } from "react"
import { parseDate } from "@internationalized/date"
 
import { DateRangePicker } from "@/components/ui/date-range-picker"
 
export default function DateRangePickerControlled() {
  const [value, setValue] = useState({
    start: parseDate("2024-12-20"),
    end: parseDate("2024-12-27"),
  })
 
  return (
    <div className="space-y-4">
      <DateRangePicker
        label="Hotel reservation"
        description="Select your check-in and check-out dates."
        value={value}
        onChange={setValue}
      />
      <p className="text-muted-foreground text-sm">
        Selected range: {value.start.toString()} to {value.end.toString()}
      </p>
    </div>
  )
}

Min and Max Values

Rental period

mmddyyyy

Select a date range within the next 90 days.

"use client"

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

import { DateRangePicker } from "@/components/ui/date-range-picker"

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

  return (
    <DateRangePicker
      label="Rental period"
      description="Select a date range within the next 90 days."
      minValue={now}
      maxValue={now.add({ days: 90 })}
    />
  )
}

"use client"
 
import { getLocalTimeZone, today } from "@internationalized/date"
 
import { DateRangePicker } from "@/components/ui/date-range-picker"
 
export default function DateRangePickerMinMax() {
  const now = today(getLocalTimeZone())
 
  return (
    <DateRangePicker
      label="Rental period"
      description="Select a date range within the next 90 days."
      minValue={now}
      maxValue={now.add({ days: 90 })}
    />
  )
}

Unavailable Dates

Conference dates

mmddyyyy

Weekends are unavailable.

"use client"

import { getLocalTimeZone, isWeekend, today } from "@internationalized/date"
import { useLocale } from "react-aria-components"

import { DateRangePicker } from "@/components/ui/date-range-picker"

export function DateRangePickerUnavailableDates() {
  const now = today(getLocalTimeZone())
  const { locale } = useLocale()

  return (
    <DateRangePicker
      label="Conference dates"
      description="Weekends are unavailable."
      minValue={now}
      isDateUnavailable={(date) => isWeekend(date, locale)}
    />
  )
}

"use client"
 
import { getLocalTimeZone, isWeekend, today } from "@internationalized/date"
import { useLocale } from "react-aria-components"
 
import { DateRangePicker } from "@/components/ui/date-range-picker"
 
export default function DateRangePickerUnavailableDates() {
  const now = today(getLocalTimeZone())
  const { locale } = useLocale()
 
  return (
    <DateRangePicker
      label="Conference dates"
      description="Weekends are unavailable."
      minValue={now}
      isDateUnavailable={(date) => isWeekend(date, locale)}
    />
  )
}

API Reference

DateRangePicker

Prop	Type	Default	Description
`label`	`string`	-	Label text for the date range picker
`description`	`string`	-	Help text displayed below the input
`errorMessage`	`string \| ((validation: ValidationResult) => string)`	-	Error message for validation
`value`	`{ start: DateValue, end: DateValue }`	-	The current value (controlled)
`defaultValue`	`{ start: DateValue, end: DateValue }`	-	The default value (uncontrolled)
`onChange`	`(value: { start: DateValue, end: DateValue }) => void`	-	Handler called when the value changes
`minValue`	`DateValue`	-	The minimum allowed date
`maxValue`	`DateValue`	-	The maximum allowed date
`isDateUnavailable`	`(date: DateValue) => boolean`	-	Function to determine if a date is unavailable
`allowsNonContiguousRanges`	`boolean`	`false`	Whether non-contiguous ranges are allowed
`isDisabled`	`boolean`	`false`	Whether the date range picker is disabled
`isReadOnly`	`boolean`	`false`	Whether the date range picker is read-only
`isRequired`	`boolean`	`false`	Whether the date range picker is required
`placeholderValue`	`DateValue`	-	A placeholder date that controls the default values

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

Internationalization

The DateRangePicker 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 range = {
  start: parseDate("2024-12-20"),
  end: parseDate("2024-12-27"),
}

Calendar Systems

The date range picker 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.

The date range picker supports full keyboard navigation:

Tab: Move focus between the start field, end field, and calendar button
Arrow Keys: Navigate between segments in the fields, or dates in the calendar
Enter/Space: Open/close the calendar popover, or select a date
Escape: Close the calendar popover
Page Up/Down: Navigate months in the calendar
Home/End: Go to the first/last day of the week in the calendar

Use Cases

The date range picker is ideal for:

Hotel Bookings: Select check-in and check-out dates
Trip Planning: Choose travel start and end dates
Event Scheduling: Define event duration
Rental Periods: Specify rental start and end dates
Report Filters: Select date ranges for data filtering

Date Picker - For selecting a single date
Date Field - For keyboard-only date entry
Range Calendar - For visual date range selection
Calendar - For single date selection
Field - For composing accessible form fields

Date Picker Dialog

On This Page

Installation Usage About Examples Default Disabled Validation Controlled Min and Max Values Unavailable Dates API Reference DateRangePicker Internationalization Calendar Systems Keyboard Navigation Use Cases Related Components