Date Picker

InstallCopy Anchor Link

pnpm exec vegastack-design verify date-picker

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

UsageCopy Anchor Link

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

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

Inside a Field, give the trigger an id and point the FieldLabel at it, exactly as for an Input. aria-describedby and aria-invalid reach the trigger too, so a description, an error and the invalid border work the same way:

<Field data-invalid={!!error}>
  <FieldLabel htmlFor="due-date">Due date</FieldLabel>
  <DatePicker
    id="due-date"
    value={date}
    onValueChange={setDate}
    aria-describedby="due-date-error"
    aria-invalid={!!error}
  />
  <FieldError id="due-date-error">{error}</FieldError>
</Field>

The calendar engine (react-day-picker and date-fns) is not in the page's first bundle: both pickers fetch it when the trigger is hovered or focused and render it once the popup opens, so a form full of date fields costs nothing until one is used. Nothing to configure — the popup looks and behaves the same.

AnatomyCopy Anchor Link

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

ExamplesCopy Anchor Link

AnatomyCopy Anchor Link

The Date Picker module is a composition, not a calendar: the grid is Calendar, which this module imports rather than restates. Both pickers put that calendar inside a Popover opened by an outline Button. For a grid with no popover, use Calendar directly.

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

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

• 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 the DayPicker knobs Calendar forwards — timeZone, locale, footer, captionLayout, startMonth, endMonth, labels, 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, and { timeZone: useTimeZone() } so "Today" is the viewer's day.
• Today in the grid follows the TimeZoneProvider zone: both pickers mark the provider zone's calendar day as today (a calendarProps.today or calendarProps.timeZone wins). A bare Calendar is upstream's and takes today or timeZone directly.

With presetsCopy Anchor Link

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

Date rangeCopy Anchor Link

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

Disabled datesCopy Anchor Link

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 evaluator the grid applies, so the preset gate cannot drift from the grid.

DisabledCopy Anchor Link

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

Inside a FieldCopy Anchor Link

Inside a Field the trigger renders through Base UI's Field.Control, so FieldLabel names it, the rendered FieldDescription and FieldError describe it, and the Field's data-invalid marks it invalid. An explicit id still wins, and an explicit aria-describedby keeps its ids first.

ClearableCopy Anchor Link

clearable puts a clear control beside the trigger while a date is set — a sibling, never inside the trigger — named by clearLabel ("Clear date"). Clearing reports undefined and returns focus to the trigger.

Inline in a rowCopy Anchor Link

For a date inside a table row or a toolbar, size="sm" matches Select size="sm" and SearchableSelect size="sm", and variant="ghost" sizes the trigger to its content with no border at rest. renderValue replaces the formatted date with your own face, such as "Due Jun 18".

Dropdown captionCopy Anchor Link

Forward Calendar's own 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 rangeCopy Anchor Link

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

Custom formatting & localeCopy Anchor Link

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 ReferenceCopy Anchor Link

DatePickerCopy Anchor Link

DateRangePickerCopy Anchor Link

DatePresetCopy Anchor Link

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

DateRangePresetCopy Anchor Link

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

Preset helpersCopy Anchor Link

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

DateRange & MatcherCopy Anchor Link

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).

AccessibilityCopy Anchor Link

• The grid is Calendar, which renders the month as a grid of gridcell day buttons with descriptive aria-labels ("Saturday, June 21st, 2026"); its own page documents the grid's semantics in full.
• The selected day, range ends, today, and disabled days are all distinguishable by state — not by colour alone — via data-* driven surfaces (bg-primary for a selection, bg-muted for today, reduced opacity for a blocked day).
• 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.
• Opening a picker that sits below the fold does not scroll the page: the popover's day button focuses with preventScroll, because the portaled popup is still unpositioned on its first paint.
• Focus is always visible — the trigger takes the global :focus-visible outline, and the day grid manages roving focus itself.
• The trigger has no visible text label when empty beyond its placeholder, so name it: pass id and a FieldLabel htmlFor pointing at it (clicking the label then opens the picker), or aria-label when there is no visible label. aria-describedby and aria-invalid are forwarded to the trigger on both pickers.

Do / Don'tCopy Anchor Link