Crytec Registry

DateRangePicker

A date range picker with dual-month calendar, presets, external navigation, URL sync, and form integration.

Installation

CLI

Loading...

Dependencies

This component requires the following npm packages:

Loading...

Registry Dependencies

This component also requires: https://ui.shadcn.com/r/styles/base-vega/button.json, https://ui.shadcn.com/r/styles/base-vega/calendar.json, https://ui.shadcn.com/r/styles/base-vega/popover.json, https://ui.shadcn.com/r/styles/base-vega/utils.json

Usage

DateRangePicker is a highly configurable compound component for selecting date ranges. It features a dual-month calendar, preset options, external navigation controls, built-in i18n support, and SSR-friendly URL sync capabilities.

The component uses a compound component pattern, allowing you to customize the trigger, navigation, calendar, presets, and actions independently. It supports both controlled and uncontrolled usage patterns.

Examples

With Presets

Enable the presets sidebar with commonly used date ranges like "Current Month", "Last 3 Months", etc.

With Action Buttons

Add Clear, Cancel, and Apply buttons for explicit user confirmation. Set closeOnSelect to false to keep the popover open until the user clicks Apply.

Single Month

Use a single month calendar for a more compact layout. The external navigation arrows select the full previous/next month. Use the calendar's internal navigation to browse months without changing the selection.

German Locale (i18n)

Use date-fns locales for calendar display and the built-in getLocalizedPresets function for translated preset labels. Supports English, German, French, and Spanish out of the box.

Constrained Date Range

Limit selectable dates with minDate and maxDate props. Navigation buttons are automatically disabled when at the boundaries.

Fully Controlled

Control both the date range value and popover open state externally for full control over the component behavior.

From:Not selected

To:Not selected

Picker state:Closed

API Reference

DateRangePicker Props

Prop	Type	Default	Description
`value`	`DateRange`	-	The controlled value of the selected date range ({ from: Date, to?: Date }).
`defaultValue`	`DateRange`	-	The default value of the selected date range.
`onValueChange`	`(value: DateRange \| undefined) => void`	-	Callback fired when the date range selection changes.
`open`	`boolean`	-	The controlled open state of the popover.
`defaultOpen`	`boolean`	`false`	The default open state of the popover.
`onOpenChange`	`(open: boolean) => void`	-	Callback fired when the popover open state changes.
`month`	`Date`	-	The controlled month displayed in the calendar.
`defaultMonth`	`Date`	-	The default month to display in the calendar.
`onMonthChange`	`(month: Date) => void`	-	Callback fired when the displayed month changes.
`dateFormat`	`string`	`"dd.MM.yyyy"`	The date format string (date-fns format).
`dateSeparator`	`string`	`" - "`	The separator between from and to dates in display.
`placeholder`	`string`	`"Select date range"`	Placeholder text when no date is selected.
`locale`	`Locale`	-	date-fns locale for formatting and calendar display.
`presets`	`DateRangePreset[]`	-	Custom preset options. Defaults to built-in presets (Current Month, Last Month, etc.).
`onPresetSelect`	`(preset: DateRangePreset) => void`	-	Callback fired when a preset is selected.
`numberOfMonths`	`number`	`2`	Number of months to display in the calendar.
`minDate`	`Date`	-	Minimum selectable date.
`maxDate`	`Date`	-	Maximum selectable date.
`disabled`	`Matcher \| Matcher[]`	-	Days that cannot be selected (react-day-picker Matcher).
`weekStartsOn`	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`	`1`	First day of the week (0=Sunday, 1=Monday).
`showWeekNumber`	`boolean`	`false`	Show week numbers in the calendar.
`fixedWeeks`	`boolean`	`false`	Always show 6 weeks in the calendar.
`closeOnSelect`	`boolean`	`true`	Close popover automatically when a complete range is selected.
`urlParamKey`	`string`	-	URL search param key for syncing date range to URL.
`urlFormat`	`"iso" \| "timestamp"`	`"iso"`	Format for serializing dates in URL.
`onUrlChange`	`(url: string) => void`	-	Callback when URL should be updated (use with router.push).
`name`	`string`	-	Form field name for hidden input.
`required`	`boolean`	-	Whether the field is required for form submission.
`isDisabled`	`boolean`	`false`	Whether the date range picker is disabled.
`children*`	`ReactNode`	-	The trigger element and popover content.

DateRangePickerTrigger Props

Prop	Type	Default	Description
`children*`	`ReactElement`	-	The trigger element (usually a Button).
`...props`	`PopoverTriggerProps`	-	All PopoverTrigger props are supported.

DateRangePickerNavigation Props

Prop	Type	Default	Description
`hidePrevious`	`boolean`	-	Hide the previous month selection button.
`hideNext`	`boolean`	-	Hide the next month selection button.
`...props`	`div`	-	All standard div props are supported. Note: Clicking navigation buttons selects the full previous/next month as the date range.

DateRangePickerContent Props

Prop	Type	Default	Description
`showPresets`	`boolean`	`false`	Show the presets sidebar automatically.
`...props`	`PopoverContentProps`	-	All PopoverContent props are supported.

DateRangePickerActions Props

Prop	Type	Default	Description
`showClear`	`boolean`	`true`	Show the clear button.
`showCancel`	`boolean`	`true`	Show the cancel button.
`showApply`	`boolean`	`true`	Show the apply button.
`clearLabel`	`string`	`"Clear"`	Label for the clear button.
`cancelLabel`	`string`	`"Cancel"`	Label for the cancel button.
`applyLabel`	`string`	`"Apply"`	Label for the apply button.
`onApply`	`() => void`	-	Callback when apply button is clicked.

Sub-components

The following sub-components are available for customizing the date range picker interface:

DateRangePickerTrigger - Button that opens the popover
DateRangePickerNavigation - External chevron arrows that select full previous/next month
DateRangePickerContent - Popover content wrapper
DateRangePickerPresets - Preset buttons sidebar
DateRangePickerCalendar - Dual-month calendar with internal navigation
DateRangePickerDisplay - Formatted date range text
DateRangePickerActions - Footer with Clear/Cancel/Apply buttons

Utility Functions

Helper functions for common operations:

getLocalizedPresets(localeCode) - Get preset labels in specified language (en, de, fr, es)
serializeDateRange(range, format) - Serialize date range for URL
parseDateRangeFromSearchParams(param) - Parse date range from URL string
buildDateRangeUrl(baseUrl, key, range) - Build URL with date range param
useDateRangePicker() - Hook to access context within sub-components

Source Code

Loading...