DatePicker | Fragments

Preview

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

Installation

npx @usefragments/cli add datepicker

pnpm add react-day-picker

Writes src/fragments/ui/components/DatePicker plus what it imports, the globals stylesheet, and .fragments/registry-lock.json, then prints the packages to add. No account, no key.

Your own registry: publish from Fragments Cloud and add --registry org/name. Connect a workspace.

Anatomy

DatePicker is a compound: import the root and reach its parts through dot notation.

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

Trigger opens one month; today is outlined.

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

Examples

Small Trigger

Matches the height of other sm toolbar controls.

<StatefulDatePicker size="sm" placeholder="Last scanned">
  <DatePicker.Trigger />
  <DatePicker.Content>
    <DatePicker.Calendar />
  </DatePicker.Content>
</StatefulDatePicker>

Date Range

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

<StatefulRangePicker placeholder="Select date range" numberOfMonths={2}>
  <DatePicker.Trigger />
  <DatePicker.Content>
    <DatePicker.Calendar />
  </DatePicker.Content>
</StatefulRangePicker>

Multi-Month

Three months at once, for dates far from today.

<StatefulDatePicker placeholder="Pick a date" numberOfMonths={3}>
  <DatePicker.Trigger />
  <DatePicker.Content>
    <DatePicker.Calendar />
  </DatePicker.Content>
</StatefulDatePicker>

Disabled Dates

Everything before today is greyed out and unclickable.

<StatefulDatePicker
  placeholder="Select a future date"
  disabledDates={{ before: new Date() }}
>
  <DatePicker.Trigger />
  <DatePicker.Content>

With Presets

Shortcut buttons beside the calendar skip the common ranges.

<StatefulRangePicker placeholder="Select date range" numberOfMonths={2}>
  <DatePicker.Trigger />
  <DatePicker.Content>
    <div style={{ display: 'flex', gap: '1rem' }}>
      <div style={{ display: 'flex', flexDirection: 'column', gap: '0.25rem', minWidth: '8rem' }}>
        <DatePicker.Preset range={{ from: today, to: today }}>Today</DatePicker.Preset>

With Label and Helper Text

Label above the trigger, supporting text below it.

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

Error State

Red border on the trigger, and the reason below it.

<DatePicker
  label="Start Date"
  placeholder="Pick a date"
  error="Please select a start date"
>
  <DatePicker.Trigger />

Disabled

Dimmed; the calendar will not open.

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

API

Component props
Prop	Type	Default	Description
`children`Required	`node`	Not set	DatePicker trigger and content
`className`	`string`	Not set	Wrapper class name
`mode`	`enumsinglerange`	`single`	Selection mode
`selected`	`object`	Not set	Controlled date (single mode). Type: Date \| null
`selectedRange`	`object`	Not set	Controlled range (range mode). Type: DateRange \| null
`onSelect`	`function`	Not set	Called when a single date is selected
`onChange`	`function`	Not set	Alias for onSelect (consistent with Input/Select onChange convention)
`onRangeSelect`	`function`	Not set	Called when a date range is selected
`numberOfMonths`	`number`	`1`	Number of months displayed side-by-side
`disabled`	`boolean`	`false`	Disable the picker
`size`	`enumsmmdlg`	`"md"`	Trigger size variant
`disabledDates`	`union`	Not set	Dates to disable (react-day-picker Matcher \| Matcher[])
`placeholder`	`string`	Not set	Trigger placeholder text
`locale`	`object`	Not set	date-fns locale for i18n
`fixedWeeks`	`boolean`	`false`	Always show 6 rows
`formatDate`	`function`	Not set	Custom trigger date formatter
`formatRange`	`function`	Not set	Custom trigger range formatter
`open`	`boolean`	Not set	Controlled popover open state
`onOpenChange`	`function`	Not set	Popover open state change callback
`name`	`string`	Not set	Hidden input name for forms
`label`	`string`	Not set	Visible label text above the date picker
`helperText`	`string`	Not set	Helper text shown below the date picker
`error`	`union`	Not set	Show error styling. When a string is provided, it is displayed as an error message.

Accessibility

The calendar grid is fully keyboard navigable
Arrow keys move between days
Escape closes the calendar
Focus returns to the trigger on close

Guidance

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)

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 contractThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.