Date Picker

Install

pnpm dlx shadcn@latest add @vegastack/date-picker

Usage

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

function Example() {
  const [date, setDate] = React.useState<Date>();
  return <DatePicker value={date} onValueChange={setDate} />;
}

Anatomy

Date Picker is a compound component. Every exported part, with the data-slot it renders (generated from the canonical source):

Examples

Anatomy

The Date Picker module exports three building blocks. DatePicker and DateRangePicker compose a Calendar inside a Popover; use Calendar directly when you want an inline grid.

// Single date — Button-triggered Popover hosting a Calendar.
<DatePicker
  value={date}
  onValueChange={setDate}
  presets={defaultDatePresets()}
  calendarProps={{ timeZone: 'UTC', captionLayout: 'dropdown' }}
/>

// Range — two-month Calendar, closes once both ends are chosen.
<DateRangePicker value={range} onValueChange={setRange} />

// Inline — the styled DayPicker with no popover.
<Calendar mode="single" selected={date} onSelect={setDate} />

• Calendar — a token-styled react-day-picker DayPicker (data-slot="calendar"). Forwards every DayPicker prop (mode, selected, onSelect, defaultMonth, numberOfMonths, disabled, …); overrides the nav chevrons (lucide) and the day button.
• CalendarDayButton — the per-day Button (data-slot="calendar-day"). Paints selection/range/today state from data-* attributes and auto-focuses on keyboard navigation.
• DatePicker — single date. An outline Button (data-slot="date-picker-trigger") shows the formatted date and opens the calendar in a Popover (data-slot="date-picker-content"). Pass calendarProps for DayPicker knobs such as timeZone, locale, footer, captionLayout, startMonth, endMonth, labels, and formatters.
• DateRangePicker — a { from, to } range, same shape, across two months (data-slot="date-range-picker-trigger" / …-content). It also accepts calendarProps; top-level selection props remain owned by the wrapper.
• defaultDatePresets() / defaultRangePresets() — ready-made quick-select rails (Today / Tomorrow, Last 7 / 30 days). Pass your own presets to override.

Date and range selection

With presets

A left rail of quick-select buttons (Today / Tomorrow) sits beside the calendar. Selecting a preset closes the popover.

Date range

Pick a start and end across two months. The popover stays open until both ends are chosen; presets cover common windows.

Inline calendar

The bare Calendar with no popover — drop it into a card or sidebar.

Disabled dates

Pass disabledDates (a single Matcher, or an array) to block days in the grid and gate presets. A blocked day renders at reduced opacity and can't be selected; a preset whose date — or, for ranges, any day it spans — falls inside the blocked set is rendered inert and never emits, using the same react-day-picker matcher the grid applies (so the preset gate can't drift from the grid).

Disabled

Set disabled to make the whole control inert — the trigger reads dimmed and won't open the popover.

Dropdown caption

Forward DayPicker knobs through calendarProps. Here captionLayout="dropdown" (bounded by startMonth / endMonth) swaps the static month/year heading for navigable dropdowns — handy for jumping across years.

<DatePicker
  value={date}
  onValueChange={setDate}
  calendarProps={{
    captionLayout: "dropdown",
    startMonth: new Date(2024, 0),
    endMonth: new Date(2027, 11),
  }}
/>

Single-month range

DateRangePicker shows two months by default; pass numberOfMonths={1} for a compact single-month grid that fits tight layouts.

Custom formatting & locale

The trigger label is formatted with native Intl.DateTimeFormat — no date library. The default is the readable Jun 24, 2026 ({ year: 'numeric', month: 'short', day: 'numeric' }), never an ISO string and never the browser's date-input format. Pass formatOptions for any other shape and locale for a BCP-47 locale.

API Reference

DatePicker

DateRangePicker

Calendar

CalendarDayButton

DatePreset

The shape of each entry in DatePicker's presets array.

DatePreset

DateRangePreset

The shape of each entry in DateRangePicker's presets array.

DateRangePreset

Preset helpers

Ready-made preset rails. Pass your own presets to override either.

DateRange & Matcher

Re-exported from react-day-picker. DateRange is the shape of a range value; Matcher is what disabledDates accepts (a single matcher or an array).

Accessibility

• Built on react-day-picker, which renders the month as a grid of gridcell day buttons with descriptive aria-labels ("Saturday, June 21st, 2026").
• The selected day, range ends, today, and disabled days are all distinguishable by state — not by color alone — via data-* driven surfaces (bg-primary, ring, bg-accent, reduced opacity).
• Opening the picker moves focus into the calendar; arrow keys move day-to-day, and selection restores focus to the trigger. Pressing Esc closes the popover.
• Focus is always visible: the outline Button trigger brightens its border on :focus-visible (focus-visible:border-ring/(--alpha-tint-border)), and the day grid manages roving focus itself (react-day-picker focuses the active day on keyboard navigation). Today's cell additionally carries a neutral ring (ring-ring/(--alpha-outline-soft)).
• The trigger has no visible text label when empty beyond its placeholder, so pass aria-label (or wrap it in a Field) to name it for assistive tech.

Do / Don't