DatePicker

Setup

import { DatePicker } from '@fragments-sdk/ui';

Examples

Loading preview...

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.

Usage Guidelines

When to use

Selecting a single date from a calendar
Selecting a date range (start/end)
Date inputs in forms
Filtering by date or date range

When not to use

Time-only input - use a dedicated TimePicker
Selecting from a small set of known dates - use Select
Free-form date entry - use Input with date masking

Best practices

Use range mode with numberOfMonths={2} for date range selection
Use size="sm" in dense toolbars so DatePicker aligns with Input, Select, Combobox, Button, and IconButton
Add presets for common ranges (Today, Last 7 days, Last 30 days)
Use disabledDates to prevent selecting past dates or unavailable dates
Provide a meaningful placeholder
DatePicker.Trigger forwards button props and defaults to type="button" (safe inside forms)

Accessibility

Full keyboard navigation within the calendar grid
Arrow keys navigate between days
Escape closes the calendar
Focus returns to trigger on close

Selectalternative

Use Select for choosing from a list of options

Inputsibling

Use Input for free-form text date entry

Popovercomposition

DatePicker uses Popover for the calendar dropdown

Setup

Examples

Default

Small Trigger

Date Range

Multi-Month

Disabled Dates

With Presets

With Label and Helper Text

Error State

Disabled

Props

Usage Guidelines

When to use

When not to use

Best practices

Setup

Examples

Default

Small Trigger

Date Range

Multi-Month

Disabled Dates

With Presets

With Label and Helper Text

Error State

Disabled

Props

Usage Guidelines

When to use

When not to use

Best practices

Related Components