Date Range Picker

A date field that opens a calendar for picking a start and end date

The date range picker is a field that opens a calendar popover for choosing a start and end date. Use it for report ranges, booking windows, and date filters.

To select a single date, use DatePicker instead.

Installation

npxnpx shadcn@latest add @cubby-ui/date-range-picker

Usage


import {
  DateRangePicker,
  type DateRangeValue,
} from "@/components/ui/cubby-ui/date-range-picker";


<DateRangePicker />

Examples

The value changes only after you pick both ends; closing the popover halfway keeps the previous range.

Use editable to make the field a text input. It reads two dates joined by a dash, "to", or "until" ("mar 3 – 12", "today to fri", "Dec 28 – Jan 4"), relative spans like "last 30 days" or "next 2 weeks", and a single date as a one-day range. A second date missing its month or year takes them from the first, so the field also parses its own output, "Oct 1 – 8, 2026". Before you commit, the hint shows the range and its length, or why it breaks minNights, maxNights, or a blocked date.

Presets

Use presets to add one-click ranges beside the calendar. Give each a function so ranges like "Last 7 days" resolve when the picker opens; the preset matching the current range is marked.

Status Line

Use showStatus to show the range being picked and its length under the calendar. It's off by default, since the trigger shows the finished range.

Minimum and Maximum Length

Use minNights and maxNights to limit the range's length, counted in nights between the ends, and minDate and maxDate to limit where it falls. For stays, set labels.duration to count nights instead of days in the status line and its announcement.

import { DateRangePicker } from "@/components/ui/cubby-ui/date-range-picker";
 
export default function DateRangePickerMinMaxNights() {
  return (
    <DateRangePicker
      placeholder="Book a stay"

One Month

Use numberOfMonths to fix the month count. By default the picker shows two months from the sm breakpoint up and one below it.

import { DateRangePicker } from "@/components/ui/cubby-ui/date-range-picker";
 
export default function DateRangePickerOneMonth() {
  return (
    <DateRangePicker numberOfMonths={1} placeholder="One month at a time" />
  );

With Custom Format

Use format to control how the range is written. It takes { from, to } and returns a string; the default is the locale's compact range, such as "Oct 3 – 12, 2026".

import { DateRangePicker } from "@/components/ui/cubby-ui/date-range-picker";
 
const numeric = new Intl.DateTimeFormat(undefined, {
  day: "2-digit",
  month: "2-digit",
  year: "numeric",

With Placeholder

Use placeholder to set the trigger's empty-state text.

import { DateRangePicker } from "@/components/ui/cubby-ui/date-range-picker";
 
export default function DateRangePickerWithPlaceholder() {
  return <DateRangePicker placeholder="Check-in – Check-out" />;
}

Disabled State

Use disabled to stop the picker from opening.

import { DateRangePicker } from "@/components/ui/cubby-ui/date-range-picker";
 
const today = new Date();
 
export default function DateRangePickerDisabledState() {
  return (

Accessibility

The trigger is a button that opens the calendar in a popover and moves focus into it. Use the arrow keys to move between days and Enter or Space to set the start and then the end; the preview band follows keyboard focus as well as the pointer. A polite live region announces each step to screen readers ("pick an end date", then the finished range and its length), whether or not showStatus displays it. Escape closes the popover without a change.