Date Picker

Due date

mmddyyyy

import { DatePicker } from "@/components/ui/date-picker";

export default function DatePickerDemo() {
  return <DatePicker label="Due date" className="w-full max-w-60" />;
}

Installation

$ pnpm dlx shadcn@latest add @desyne/date-picker

The CLI installs dependencies and any other components this one uses.

Usage

tsx

import { DatePicker, DateRangePicker } from "@/components/ui/date-picker";

tsx

<DatePicker label="Due date" />
<DateRangePicker label="Trip dates" />

Values are @internationalized/date objects

value is a CalendarDate (or CalendarDateTime / ZonedDateTime when you need a time), and ranges are { start, end }. Create values with today(), parseDate() or parseZonedDateTime() from @internationalized/date, and store them with value.toString().

When to use

Date Picker — the default for dates in forms. Typing is fast for known dates; the calendar helps with relative ones ("the second Friday").
Date Range Picker — a start and end date in one field: bookings, reports, leave requests.
Date Field — typed entry only, for dates far from today (birthdays) where a calendar would need many clicks.
Calendar — an always-visible grid, when there's room on the page.

Anatomy

tsx

<DatePicker>                 {/* or <DateRangePicker> */}
  <Label />
  <FieldGroup>               {/* field chrome */}
    <DateInput />            {/* segments; start + end for ranges */}
    <Button />               {/* opens the calendar */}
  </FieldGroup>
  <Description />
  <FieldError />
  <Popover>
    <Dialog>
      <Calendar />           {/* or <RangeCalendar> */}
    </Dialog>
  </Popover>
</DatePicker>

Part	Renders	Notes
`DatePicker`	`<div>`	Root. `data-slot="date-picker"`.
`DateRangePicker`	`<div>`	Root for ranges. `data-slot="date-range-picker"`.
Group	`<div role="group">`	`FieldGroup` with the shared `variant` / `size` styles. Highlights while the popover is open.
Date input	`<div>`	Segmented input, styled with `dateSegmentStyles`. Ranges render a `start` and `end` input with an arrow between.
Trigger	`<button>`	Ghost icon `Button` with a calendar icon.
Label / Description / FieldError	`<span>`	Rendered from `label`, `description` and validation.
Popover	`Popover` › `Dialog`	Placed `bottom start`, flips when there's no room.
Calendar	`Calendar` / `RangeCalendar`	The same Calendar. Inherits `minValue`, `maxValue`, `isDateUnavailable`, `firstDayOfWeek` and `pageBehavior` from the picker.

Examples

Controlled

value and onChange own the value; set it to null to clear.

Renewal date

10192026

Renews Monday, October 19, 2026

import {
  type CalendarDate,
  DateFormatter,
  getLocalTimeZone,
  today,
} from "@internationalized/date";
import { useState } from "react";
import { useLocale } from "react-aria-components";
import { DatePicker } from "@/components/ui/date-picker";

export default function DatePickerControlled() {
  const { locale } = useLocale();
  const [date, setDate] = useState<CalendarDate | null>(
    today(getLocalTimeZone()).add({ weeks: 2 }),
  );
  const formatter = new DateFormatter(locale, { dateStyle: "full" });
  return (
    <div className="flex w-full max-w-60 flex-col gap-3">
      <DatePicker label="Renewal date" value={date} onChange={setDate} />
      <p className="text-muted-foreground text-xs">
        {date
          ? `Renews ${formatter.format(date.toDate(getLocalTimeZone()))}`
          : "No renewal date"}
      </p>
    </div>
  );
}

Range

DateRangePicker edits a { start, end } range with two segmented inputs and a RangeCalendar. Picking in the calendar sets both at once.

Trip dates

10192026

10262026

import { getLocalTimeZone, today } from "@internationalized/date";
import { DateRangePicker } from "@/components/ui/date-picker";

export default function DateRangePickerDemo() {
  const now = today(getLocalTimeZone());
  return (
    <DateRangePicker
      label="Trip dates"
      defaultValue={{
        start: now.add({ days: 14 }),
        end: now.add({ days: 21 }),
      }}
      className="w-full max-w-80"
    />
  );
}

Variants

Outline

mmddyyyy

Filled

mmddyyyy

Underlined

mmddyyyy

import { DatePicker } from "@/components/ui/date-picker";

export default function DatePickerVariants() {
  return (
    <div className="flex w-full max-w-60 flex-col gap-5">
      <DatePicker label="Outline" variant="outline" />
      <DatePicker label="Filled" variant="filled" />
      <DatePicker label="Underlined" variant="underlined" />
    </div>
  );
}

Sizes

Small

mmddyyyy

Medium

mmddyyyy

Large

mmddyyyy

import { DatePicker } from "@/components/ui/date-picker";

export default function DatePickerSizes() {
  return (
    <div className="flex w-full max-w-60 flex-col gap-5">
      <DatePicker label="Small" size="sm" />
      <DatePicker label="Medium" size="md" />
      <DatePicker label="Large" size="lg" />
    </div>
  );
}

Min and max

Dates outside minValue / maxValue are disabled in the calendar, and typed values outside them are flagged invalid with a localized message. Here validationBehavior="aria" shows the error straight away; with the default native behavior it appears after the value changes or the form is submitted.

Start date

1032026

Within the next three months.Value must be 10/5/2026 or later.

import { getLocalTimeZone, today } from "@internationalized/date";
import { DatePicker } from "@/components/ui/date-picker";

export default function DatePickerValidation() {
  const now = today(getLocalTimeZone());
  return (
    <DatePicker
      label="Start date"
      validationBehavior="aria"
      minValue={now}
      maxValue={now.add({ months: 3 })}
      defaultValue={now.subtract({ days: 2 })}
      description="Within the next three months."
      className="w-full max-w-60"
    />
  );
}

Month and year dropdowns

captionLayout, fromYear and toYear are passed to the calendar in the popover (see Calendar). Use captionLayout="dropdown" for dates years away from today, like a date of birth, so nobody has to click back month by month. placeholderValue sets the month the calendar opens on.

Date of birth

mmddyyyy

Pick a month and year from the calendar header.

import {
  type CalendarDate,
  getLocalTimeZone,
  today,
} from "@internationalized/date";
import { useState } from "react";
import { DatePicker } from "@/components/ui/date-picker";

export default function DatePickerBirthday() {
  const now = today(getLocalTimeZone());
  const [value, setValue] = useState<CalendarDate | null>(null);
  const age = value
    ? now.year -
      value.year -
      (now.compare(value.set({ year: now.year })) < 0 ? 1 : 0)
    : null;
  return (
    <div className="flex w-full max-w-xs flex-col gap-3">
      <DatePicker
        label="Date of birth"
        description="Pick a month and year from the calendar header."
        captionLayout="dropdown"
        fromYear={1940}
        maxValue={now}
        placeholderValue={now.set({ year: 1990, month: 1, day: 1 })}
        value={value}
        onChange={setValue}
      />
      {age != null && (
        <p className="text-muted-foreground text-sm">
          Age: <span className="font-medium text-foreground">{age}</span>
        </p>
      )}
    </div>
  );
}

The range picker takes the same props. Here the year list is limited to this year and next by minValue and maxValue.

Check-in and check-out

mmddyyyy

Reservations open up to a year ahead.

import { getLocalTimeZone, today } from "@internationalized/date";
import { DateRangePicker } from "@/components/ui/date-picker";

export default function DatePickerBooking() {
  const now = today(getLocalTimeZone());
  return (
    <DateRangePicker
      label="Check-in and check-out"
      description="Reservations open up to a year ahead."
      captionLayout="dropdown"
      minValue={now}
      maxValue={now.add({ years: 1 })}
      className="w-full max-w-xs"
    />
  );
}

Unavailable dates

isDateUnavailable strikes dates through in the calendar and marks a typed unavailable date invalid.

Pickup date

mmddyyyy

Weekdays only, excluding public holidays.

import {
  type DateValue,
  getLocalTimeZone,
  isWeekend,
  parseDate,
  today,
} from "@internationalized/date";
import { useLocale } from "react-aria-components";
import { DatePicker } from "@/components/ui/date-picker";

// Public holidays the warehouse is closed.
const holidays = ["2026-11-26", "2026-12-25", "2027-01-01"].map((d) =>
  parseDate(d),
);

export default function DatePickerUnavailable() {
  const { locale } = useLocale();
  return (
    <DatePicker
      label="Pickup date"
      minValue={today(getLocalTimeZone()).add({ days: 1 })}
      isDateUnavailable={(date: DateValue) =>
        isWeekend(date, locale) || holidays.some((h) => h.compare(date) === 0)
      }
      description="Weekdays only, excluding public holidays."
      className="w-full max-w-60"
    />
  );
}

Date and time

With granularity="minute" (or hour / second) the field adds time segments. The calendar picks the date and keeps the time. Use a ZonedDateTime for a specific time zone, hideTimeZone to hide its abbreviation, and hourCycle to force a 12- or 24-hour clock.

Reminder

1052026841PM

Maintenance window (UTC)

2620270200UTC

import {
  getLocalTimeZone,
  now,
  parseZonedDateTime,
} from "@internationalized/date";
import { DatePicker } from "@/components/ui/date-picker";

export default function DatePickerDateTime() {
  return (
    <div className="flex w-full max-w-72 flex-col gap-5">
      <DatePicker
        label="Reminder"
        granularity="minute"
        defaultValue={now(getLocalTimeZone())
          .add({ hours: 2 })
          .set({ second: 0, millisecond: 0 })}
        hideTimeZone
      />
      <DatePicker
        label="Maintenance window (UTC)"
        granularity="minute"
        hourCycle={24}
        defaultValue={parseZonedDateTime("2027-02-06T02:00[UTC]")}
      />
    </div>
  );
}

Range validation

validate receives the whole range. Combine it with isRequired and minValue; with validationBehavior="aria" on the form, errors update live.

import { getLocalTimeZone, today } from "@internationalized/date";
import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { DateRangePicker } from "@/components/ui/date-picker";

const MAX_DAYS = 14;

export default function DateRangePickerValidation() {
  const now = today(getLocalTimeZone());
  return (
    <Form
      validationBehavior="aria"
      className="flex w-full max-w-80 flex-col gap-4"
      onSubmit={(e) => e.preventDefault()}
    >
      <DateRangePicker
        label="Vacation"
        isRequired
        minValue={now}
        defaultValue={{
          start: now.add({ days: 7 }),
          end: now.add({ days: 25 }),
        }}
        validate={(range) =>
          range && range.end.compare(range.start) >= MAX_DAYS
            ? `Requests are limited to ${MAX_DAYS} days. Split longer leave into two requests.`
            : null
        }
        description={`Up to ${MAX_DAYS} days per request.`}
      />
      <Button type="submit" className="self-start">
        Submit request
      </Button>
    </Form>
  );
}

Form submission

name submits a DatePicker value as an ISO 8601 string. DateRangePicker submits two fields, named with startName and endName.

import { useState } from "react";
import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { DatePicker, DateRangePicker } from "@/components/ui/date-picker";

export default function DatePickerForm() {
  const [data, setData] = useState<Record<string, FormDataEntryValue> | null>(
    null,
  );
  return (
    <Form
      className="flex w-full max-w-80 flex-col gap-4"
      onSubmit={(e) => {
        e.preventDefault();
        setData(Object.fromEntries(new FormData(e.currentTarget)));
      }}
    >
      <DatePicker label="Publish on" name="publishAt" isRequired />
      <DateRangePicker
        label="Promotion"
        startName="promoStart"
        endName="promoEnd"
        isRequired
      />
      <Button type="submit" className="self-start">
        Save
      </Button>
      {data && (
        <code className="rounded-md bg-muted px-2 py-1 text-xs break-all">
          {JSON.stringify(data)}
        </code>
      )}
    </Form>
  );
}

Locales and first day of the week

Format, segment order and the calendar's first weekday follow the locale. Wrap pickers in I18nProvider to set one, or override the week start with firstDayOfWeek.

English (UK)

ddmmyyyy

German

ttmmjjjj

Week starts on Monday

mmddyyyy

import { I18nProvider } from "react-aria-components";
import { DatePicker } from "@/components/ui/date-picker";

export default function DatePickerLocales() {
  return (
    <div className="flex w-full max-w-60 flex-col gap-5">
      <I18nProvider locale="en-GB">
        <DatePicker label="English (UK)" />
      </I18nProvider>
      <I18nProvider locale="de-DE">
        <DatePicker label="German" />
      </I18nProvider>
      <DatePicker label="Week starts on Monday" firstDayOfWeek="mon" />
    </div>
  );
}

Disabled and read-only

isDisabled disables the segments and the trigger. isReadOnly keeps the value focusable and readable, but the calendar can't open.

Signed on

4122026

Effective from

512026

import { parseDate } from "@internationalized/date";
import { DatePicker } from "@/components/ui/date-picker";

export default function DatePickerDisabled() {
  return (
    <div className="flex w-full max-w-60 flex-col gap-5">
      <DatePicker
        label="Signed on"
        defaultValue={parseDate("2026-04-12")}
        isDisabled
      />
      <DatePicker
        label="Effective from"
        defaultValue={parseDate("2026-05-01")}
        isReadOnly
      />
    </div>
  );
}

Controlled open state

isOpen and onOpenChange control the popover, for example to open it from another button. shouldCloseOnSelect={false} keeps it open after a date is picked.

Follow-up

mmddyyyy

Stays open after picking. Press Esc or click outside to close.

import { useState } from "react";
import { Button } from "@/components/ui/button";
import { DatePicker } from "@/components/ui/date-picker";

export default function DatePickerControlledOpen() {
  const [open, setOpen] = useState(false);
  return (
    <div className="flex w-full max-w-60 flex-col gap-3">
      <DatePicker
        label="Follow-up"
        isOpen={open}
        onOpenChange={setOpen}
        shouldCloseOnSelect={false}
        description="Stays open after picking. Press Esc or click outside to close."
      />
      <Button
        size="sm"
        variant="outline"
        className="self-start"
        onPress={() => setOpen(true)}
      >
        Open calendar
      </Button>
    </div>
  );
}

Recipes

Report period with presets

A preset Select next to a DateRangePicker. Choosing a preset fills the range; editing the range switches the preset to "Custom". maxValue blocks future dates.

Period

962026

1052026

import {
  type CalendarDate,
  getLocalTimeZone,
  startOfMonth,
  startOfYear,
  today,
} from "@internationalized/date";
import { CalendarRangeIcon } from "lucide-react";
import { useState } from "react";
import type { Key, RangeValue } from "react-aria-components";
import { DateRangePicker } from "@/components/ui/date-picker";
import { Select, SelectItem } from "@/components/ui/select";

type Range = RangeValue<CalendarDate>;

function presetRange(id: Key, now: CalendarDate): Range | null {
  switch (id) {
    case "7d":
      return { start: now.subtract({ days: 6 }), end: now };
    case "30d":
      return { start: now.subtract({ days: 29 }), end: now };
    case "90d":
      return { start: now.subtract({ days: 89 }), end: now };
    case "mtd":
      return { start: startOfMonth(now), end: now };
    case "ytd":
      return { start: startOfYear(now), end: now };
    default:
      return null;
  }
}

export default function DatePickerRecipeReportRange() {
  const now = today(getLocalTimeZone());
  const [preset, setPreset] = useState<Key | null>("30d");
  const [range, setRange] = useState<Range | null>(presetRange("30d", now));

  return (
    <div className="flex w-full max-w-xl flex-wrap items-end gap-2 rounded-lg border bg-card p-3 shadow-xs">
      <Select
        label="Period"
        size="sm"
        prefix={<CalendarRangeIcon />}
        selectedKey={preset}
        onSelectionChange={(key) => {
          setPreset(key);
          if (key && key !== "custom") setRange(presetRange(key, now));
        }}
        className="w-44"
      >
        <SelectItem id="7d">Last 7 days</SelectItem>
        <SelectItem id="30d">Last 30 days</SelectItem>
        <SelectItem id="90d">Last 90 days</SelectItem>
        <SelectItem id="mtd">Month to date</SelectItem>
        <SelectItem id="ytd">Year to date</SelectItem>
        <SelectItem id="custom">Custom</SelectItem>
      </Select>
      <DateRangePicker
        aria-label="Custom range"
        size="sm"
        value={range}
        onChange={(value) => {
          setRange(value);
          setPreset("custom");
        }}
        maxValue={now}
        className="w-auto min-w-64 flex-1"
      />
    </div>
  );
}

Hotel search

A native <form> with a required range (sold-out nights unavailable, the night count in the description), startName / endName for submission, and a NumberField for guests.

import {
  type CalendarDate,
  type DateValue,
  getLocalTimeZone,
  today,
} from "@internationalized/date";
import { useState } from "react";
import type { RangeValue } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { DateRangePicker } from "@/components/ui/date-picker";
import { NumberField } from "@/components/ui/number-field";

export default function DatePickerRecipeTravel() {
  const now = today(getLocalTimeZone());
  const soldOut = [now.add({ days: 9 }), now.add({ days: 10 })];
  const [stay, setStay] = useState<RangeValue<CalendarDate> | null>(null);
  const nights = stay ? stay.end.compare(stay.start) : 0;

  return (
    <form
      className="flex w-full max-w-sm flex-col gap-4 rounded-xl border bg-card p-4 shadow-xs"
      onSubmit={(e) => e.preventDefault()}
    >
      <h3 className="font-semibold text-sm">Find a room</h3>
      <DateRangePicker
        label="Check-in → check-out"
        value={stay}
        onChange={setStay}
        minValue={now}
        maxValue={now.add({ years: 1 })}
        isDateUnavailable={(date: DateValue) =>
          soldOut.some((d) => d.compare(date) === 0)
        }
        startName="checkIn"
        endName="checkOut"
        isRequired
        description={
          nights > 0
            ? `${nights} ${nights === 1 ? "night" : "nights"}`
            : "Sold-out nights are struck through."
        }
      />
      <NumberField
        label="Guests"
        name="guests"
        defaultValue={2}
        minValue={1}
        maxValue={8}
      />
      <Button type="submit">Search availability</Button>
    </form>
  );
}

Quick picks

Shortcut buttons under the field for common due dates. They set the same controlled value the picker uses, and the active one is highlighted.

Due date

mmddyyyy

import {
  type CalendarDate,
  getLocalTimeZone,
  startOfWeek,
  today,
} from "@internationalized/date";
import { useState } from "react";
import { useLocale } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { DatePicker } from "@/components/ui/date-picker";

export default function DatePickerRecipeQuickDates() {
  const { locale } = useLocale();
  const now = today(getLocalTimeZone());
  const [due, setDue] = useState<CalendarDate | null>(null);
  const quick = [
    { label: "Today", date: now },
    { label: "Tomorrow", date: now.add({ days: 1 }) },
    {
      label: "Next week",
      date: startOfWeek(now.add({ weeks: 1 }), locale, "mon"),
    },
    { label: "In 2 weeks", date: now.add({ weeks: 2 }) },
  ];
  return (
    <div className="flex w-full max-w-72 flex-col gap-2">
      <DatePicker
        label="Due date"
        value={due}
        onChange={setDue}
        minValue={now}
      />
      <div className="flex flex-wrap gap-1">
        {quick.map((q) => (
          <Button
            key={q.label}
            size="xs"
            variant={due?.compare(q.date) === 0 ? "soft" : "outline"}
            onPress={() => setDue(q.date)}
          >
            {q.label}
          </Button>
        ))}
        {due && (
          <Button size="xs" variant="ghost" onPress={() => setDue(null)}>
            Clear
          </Button>
        )}
      </div>
    </div>
  );
}

Accessibility

The field is a role="group" labelled by label. Segments are spin buttons, exactly like Date Field.
The trigger button is labelled "Calendar" together with the field label, and is disabled when the picker is disabled or read-only.
The popover is a dialog. Focus moves into the calendar when it opens (to the selected date, or today) and returns to the field when it closes.
Everything outside the popover is hidden from screen readers while it's open.
description and the error message are linked with aria-describedby; invalid pickers set aria-invalid.
Always provide a label: label, aria-label, or aria-labelledby.

Keyboard

Key	Action
`Alt`+`↓` / `Alt`+`↑`	Opens the calendar from the field
`Space` / `Enter`	Opens the calendar from the trigger button
`←` / `→` / `↑` / `↓`	In the field: moves between / steps segments. In the calendar: moves between days
`Page Up` / `Page Down`	In the calendar: previous / next month
`Enter` / `Space`	In the calendar: selects the focused date and closes
`Esc`	Closes the calendar and returns focus to the field

See Calendar and Date Field for the full lists.

Styling

Data attributes

On the DatePicker / DateRangePicker root (use group-data-*/field: for children):

Attribute	Present when
`data-open`	The calendar popover is open (the group border uses it)
`data-focus-within` / `data-focus-visible`	Something inside has focus / keyboard focus
`data-invalid`	Validation failed or `isInvalid` is set
`data-disabled`	`isDisabled` is true
`data-readonly`	`isReadOnly` is true
`data-required`	`isRequired` is true

On the field group:

Attribute	Present when
`data-hovered`	Hovered with a mouse
`data-focus-within` / `data-focus-visible`	A segment or the trigger has focus / keyboard focus
`data-invalid` / `data-disabled`	Mirrors the picker

Segments expose the same attributes as in Date Field, and calendar cells as in Calendar.

Slots

`data-slot`	Element
`date-picker` / `date-range-picker`	Root
`field-group`	Field chrome
`button`	Calendar trigger
`label`, `description`, `field-error`	Field text
`popover`	Calendar popover
`calendar` / `range-calendar`	Calendar inside the popover

Customizing

className sizes and positions the whole picker (e.g. w-full max-w-60). It also accepts a function of the render props.
The field chrome uses the shared fieldVariants, so pickers line up with text fields and selects of the same size.
Segments use the exported dateSegmentStyles from Date Field.
The popover and calendar are fixed parts. For a different popover layout (presets beside the calendar, two months), compose React Aria's DatePicker with this library's Popover and Calendar.

API Reference

DatePicker

Prop

Type

Also accepts every prop of React Aria's DatePicker.

DateRangePicker

Accepts the same props as DatePicker, with range values:

Prop

Type

Also accepts every prop of React Aria's DateRangePicker.

Calendar — the calendar on its own, including multiple months and multi-date selection.
Date Field — typed dates and times, and TimeField.
Popover — for building custom picker layouts.
Select — pairs well with range pickers for presets.