React DatePicker component

Preview

<DatePicker label="Start date" placeholder="Pick a date">
  <DatePicker.Trigger />
  <DatePicker.Content>
    <DatePicker.Calendar />
  </DatePicker.Content>
</DatePicker>

Usage

Use when

A date the user picks off a calendar
A start and end date together
Filtering by date

Avoid when

Time on its own (use a dedicated TimePicker)
A handful of known dates (use Select)
Typed date entry (use Input with a date mask)

Implementation notes

Pair range mode with numberOfMonths={2} so both ends are visible
size="sm" lines the trigger up with other dense toolbar controls
Offer at most a few presets for the common ranges: Today, Last 7 days, Last 30 days
disabledDates blocks past or unavailable days before the user tries
Placeholder names the date, not the action
A single pick closes the calendar at once; a range stays open until Escape or an outside click
DatePicker.Trigger defaults to type="button", so it is safe inside a form

Installation

pnpm add @usefragments/ui

Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Additional packages

react-day-picker — Optional — renders the calendar popup; the trigger and form field work without it.

pnpm add react-day-picker

Anatomy

Import DatePicker once, then compose its parts with dot notation.

DatePicker.Trigger
DatePicker.Content
DatePicker.Calendar
DatePicker.Preset
DatePicker.preload

Trigger opens one month; today carries the strong line.

<DatePicker label="Start date" placeholder="Pick a date">
  <DatePicker.Trigger />
  <DatePicker.Content>
    <DatePicker.Calendar />
  </DatePicker.Content>
</DatePicker>

Examples

Controlled

One value and one callback.

const [date, setDate] = React.useState<Date | null>(null);

<DatePicker label="Start date" value={date} onValueChange={setDate}>
  <DatePicker.Trigger />
  <DatePicker.Content>
    <DatePicker.Calendar />

Small Trigger

Matches the height of other sm toolbar controls.

<DatePicker size="sm" label="Last scanned" placeholder="Any time">
  <DatePicker.Trigger />
  <DatePicker.Content>
    <DatePicker.Calendar />
  </DatePicker.Content>
</DatePicker>

Date Range

Two months side by side so both ends of the range are visible.

import type { DateRange } from "@usefragments/ui";

const [range, setRange] = React.useState<DateRange | null>(null);

<DatePicker
  mode="range"

Disabled Dates

Days before today are struck through and unclickable.

<DatePicker
  label="Ships on"
  placeholder="Select a future date"
  disabledDates={(date) => date < new Date(new Date().setHours(0, 0, 0, 0))}
>
  <DatePicker.Trigger />

With Presets

A few ghost buttons above the calendar skip the common ranges.

const today = new Date(2026, 9, 4);
const weekAgo = new Date(2026, 8, 28);

<DatePicker mode="range" label="Window" numberOfMonths={2}>
  <DatePicker.Trigger />
  <DatePicker.Content>

With Helper Text

Label above the trigger, supporting text below it.

<DatePicker
  label="Renewal date"
  placeholder="Pick a date"
  helperText="Billing restarts on this day each month."
>
  <DatePicker.Trigger />

Invalid

The danger edge on the trigger, and the reason below it with an icon.

<DatePicker
  label="Start date"
  placeholder="Pick a date"
  invalid
  errorMessage="Pick a start date before the end date"
>

Read Only

The value with a dashed edge; the calendar stays shut.

<DatePicker label="Start date" defaultValue={new Date(2026, 9, 3)} readOnly>
  <DatePicker.Trigger />
  <DatePicker.Content>
    <DatePicker.Calendar />
  </DatePicker.Content>
</DatePicker>

Disabled

Dimmed; the calendar will not open.

<DatePicker label="Start date" placeholder="Pick a date" disabled>
  <DatePicker.Trigger />
  <DatePicker.Content>
    <DatePicker.Calendar />
  </DatePicker.Content>
</DatePicker>

API reference

Component props
Prop	Type	Default	Description
`Calendar.className`	`string \| undefined`	Not set	—
`Calendar.numberOfMonths`	`number \| undefined`	Not set	Override number of months from root
`children`Required	`React.ReactNode`	Not set	DatePicker trigger and content
`className`	`string \| undefined`	Not set	Wrapper class name
`Content.align`	`"center" \| "start" \| "end" \| undefinedcenterstartend`	Not set	—
`Content.children`Required	`React.ReactNode`	Not set	—
`Content.sideOffset`	`number \| undefined`	Not set	—
`defaultValue`	`Date \| DateRange \| null \| undefined`	Not set	Initial value for uncontrolled use, typed by mode
`disabled`	`boolean \| undefined`	`false`	Disable the picker
`disabledDates`	`Matcher \| Matcher[] \| undefined`	Not set	Dates to disable (react-day-picker Matcher \| Matcher[])
`errorMessage`	`string \| undefined`	Not set	Words shown under the trigger while invalid, with a warning icon
`format`	`((date: Date) => string) \| undefined`	Not set	Formats one date for the trigger. Defaults to Intl in the locale (long for single, medium for each range end); ranges join with an en dash
`helperText`	`string \| undefined`	Not set	Helper text shown below the date picker
`invalid`	`boolean \| undefined`	`false`	Marks the value invalid: the danger edge, aria-invalid and the error message
`label`	`string \| undefined`	Not set	Visible label text above the date picker
`locale`	`Locale \| undefined`	Not set	date-fns locale for i18n
`mode`	`"range" \| "single" \| undefinedrangesingle`	`single`	Selection mode
`name`	`string \| undefined`	Not set	Hidden input name for forms
`numberOfMonths`	`number \| undefined`	`1`	Number of months displayed side-by-side
`onOpenChange`	`((open: boolean) => void) \| undefined`	Not set	Popover open state change callback
`onValueChange`	`((value: Date \| null) => void) \| ((value: DateRange \| null) => void) \| undefined`	Not set	Called with the new value, typed by mode: (date: Date \| null) in single mode, (range: DateRange \| null) in range mode
`open`	`boolean \| undefined`	Not set	Controlled popover open state
`placeholder`	`string \| undefined`	Not set	Trigger placeholder text
`Preset.children`Required	`React.ReactNode`	Not set	—
`Preset.date`	`Date \| undefined`	Not set	Date to select (single mode)
`Preset.range`	`DateRange \| undefined`	Not set	Range to select (range mode)
`readOnly`	`boolean \| undefined`	`false`	Shows the value with a dashed edge; the calendar stays shut
`size`	`DatePickerSize \| undefinedsmmd`	`"md"`	Trigger size
`Trigger.children`	`React.ReactNode`	Not set	—
`Trigger.placeholder`	`string \| undefined`	Not set	—
`value`	`Date \| DateRange \| null \| undefined`	Not set	Controlled value: Date \| null in single mode, DateRange \| null in range mode

Accessibility

The visible label names the trigger, followed by the current value (aria-labelledby)
Helper and error text describe the trigger (aria-describedby); invalid sets aria-invalid
The calendar grid is fully keyboard navigable; arrow keys move between days
Escape closes the calendar and focus returns to the trigger
Read-only keeps the trigger focusable but holds the calendar shut

SelectalternativeUse Select for choosing from a list of options
InputsiblingUse Input for free-form text date entry
PopovercompositionDatePicker uses Popover for the calendar dropdown

Next steps

Accessibility guidanceThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.