Date range picker
A DateRangePicker selects a range of days on inline calendars. Its value is a DateRange: [start, end], where either end can be null. To pick a range from text fields, use Date range input.
Usage#
import { type DateRange, DateRangePicker } from "@clawscale/react/datetime";<DateRangePicker value={range} onChange={setRange} />Examples#
Basic#
The first click sets one end of the range and the second click sets the other. While the range is incomplete, one end is null. Shortcuts are on by default, so this example turns them off.
| Su | Mo | Tu | We | Th | Fr | Sa |
|---|---|---|---|---|---|---|
| Su | Mo | Tu | We | Th | Fr | Sa |
|---|---|---|---|---|---|---|
import { Tag } from "@clawscale/react";
import { type DateRange, DateRangePicker } from "@clawscale/react/datetime";
import { useState } from "react";
const pad = (n: number) => String(n).padStart(2, "0");
const isoDate = (date: Date) => `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
function describe([start, end]: DateRange) {
if (!start || !end) return "Pick the first and last day of the incident";
const days = Math.round((end.getTime() - start.getTime()) / 86_400_000) + 1;
return `Incident window: ${isoDate(start)} to ${isoDate(end)}, ${days} days`;
}
export default function DateRangePickerBasic() {
const [range, setRange] = useState<DateRange>([new Date(2026, 6, 20), new Date(2026, 6, 26)]);
return (
<div style={{ display: "grid", gap: 12, justifyItems: "center" }}>
<DateRangePicker shortcuts={false} value={range} onChange={setRange} />
<Tag minimal>{describe(range)}</Tag>
</div>
);
}Shortcuts#
The default shortcuts are ranges ending today, from Past week to Past 2 years. Pass an array of { label, dateRange } objects for your own, such as the last 7 days. Ranges built from the current date are safe on server-rendered pages, since only the labels are rendered.
| Su | Mo | Tu | We | Th | Fr | Sa |
|---|---|---|---|---|---|---|
| Su | Mo | Tu | We | Th | Fr | Sa |
|---|---|---|---|---|---|---|
import { type DateRange, DateRangePicker, type DateRangeShortcut } from "@clawscale/react/datetime";
function lastDays(days: number): DateRange {
const end = new Date();
const start = new Date(end.getFullYear(), end.getMonth(), end.getDate() - days + 1);
return [start, end];
}
export default function DateRangePickerShortcuts() {
const shortcuts: DateRangeShortcut[] = [
{ label: "Last 7 days", dateRange: lastDays(7) },
{ label: "Last 30 days", dateRange: lastDays(30) },
{ label: "Last 90 days", dateRange: lastDays(90) },
];
return <DateRangePicker shortcuts={shortcuts} defaultValue={[new Date(2026, 6, 20), new Date(2026, 6, 26)]} />;
}Single month#
The two calendars show consecutive months. singleMonthOnly shows one calendar, for popovers and side panels. contiguousCalendarMonths={false} keeps two calendars but lets each move on its own.
| Su | Mo | Tu | We | Th | Fr | Sa |
|---|---|---|---|---|---|---|
import { DateRangePicker } from "@clawscale/react/datetime";
export default function DateRangePickerSingleMonth() {
return (
<DateRangePicker singleMonthOnly shortcuts={false} defaultValue={[new Date(2026, 7, 22), new Date(2026, 7, 23)]} />
);
}Single day ranges#
By default, clicking the same day twice clears the selection. With allowSingleDayRange, it makes a one-day range, and the default shortcuts add Today and Yesterday.
| Su | Mo | Tu | We | Th | Fr | Sa |
|---|---|---|---|---|---|---|
import { DateRangePicker } from "@clawscale/react/datetime";
// A change freeze can cover a single release day.
export default function DateRangePickerSingleDay() {
return (
<DateRangePicker
allowSingleDayRange
singleMonthOnly
defaultValue={[new Date(2026, 7, 17), new Date(2026, 7, 17)]}
/>
);
}Props interface#
interface DateRangePickerProps extends Omit<DatePickerBaseProps, "dayPickerProps" | "locale" | "modifiers">, DateFnsLocaleProps, ReactDayPickerRangeProps, Props@clawscale/react/datetime| Props | Description |
|---|---|
allowSingleDayRange | boolean = falseWhether the start and end dates of the range can be the same day. If true, clicking a selected date will create a one-day range. If false, clicking a selected date will clear the selection. |
boundaryToModify | BoundaryThe date-range boundary that the next click should modify. This will be honored unless the next click would overlap the other boundary date. In that case, the two boundary dates will be auto-swapped to keep them in chronological order. If undefined, the picker will revert to its default selection behavior. |
className | stringA space-delimited list of class names to pass along to a child element. Inherited from Props |
contiguousCalendarMonths | boolean = trueWhether displayed months in the calendar are contiguous. If false, each side of the calendar can move independently to non-contiguous months. |
dateFnsLocaleLoader | DateFnsLocaleLoaderOptional custom loader function for the date-fns Inherited from Locale which will be used to localize the date picker. This is useful in test environments or in build systems where you wish to customize module loading behavior. If not provided, a default loader will be used which uses dynamic imports to load date-fns/locale/${localeCode} modules.DateFnsLocaleProps |
dayPickerProps | Omit<DayPickerRangeProps, ReactDayPickerOmittedProps>Props to pass to react-day-picker's day range picker. See API documentation here. Inherited from ReactDayPickerRangeProps |
defaultValue | DateRangeInitial DateRange the calendar will display as selected. This should not be set if value is set. |
footerElement | React.JSX.ElementAn additional element to show below the date picker. Inherited from DatePickerBaseProps |
highlightCurrentDay | boolean = falseWhether the current day should be highlighted in the calendar. Inherited from DatePickerBaseProps |
initialMonth | DateThe initial month the calendar displays. Inherited from DatePickerBaseProps |
locale | Locale | string = "en-US"date-fns Inherited from Locale object or locale code string ((ISO 639-1 + optional country code) which will be used to localize the date picker.DateFnsLocaleProps |
maxDate | Date = 6 months from now.The latest date the user can select. Inherited from DatePickerBaseProps |
minDate | Date = Jan. 1st, 20 years in the past.The earliest date the user can select. Inherited from DatePickerBaseProps |
onChange | (selectedDates: DateRange) => voidCalled when the user selects a day. If no days are selected, it will pass [null, null]. If a start date is selected but not an end date, it will pass [selectedDate, null]. If both a start and end date are selected, it will pass [startDate, endDate]. |
onHoverChange | (hoveredDates: DateRange | undefined, hoveredDay: Date, hoveredBoundary: Boundary | undefined) => voidCalled when the user changes the hovered date range, either from mouseenter or mouseleave. When triggered from mouseenter, it will pass the date range that would result from next click. When triggered from mouseleave, it will pass undefined. |
onShortcutChange | (shortcut: DateRangeShortcut, index: number) => voidCalled when the shortcuts props is enabled and the user changes the shortcut. |
reverseMonthAndYearMenus | boolean = falseIf Inherited from true, the month menu will appear to the left of the year menu. Otherwise, the month menu will apear to the right of the year menu.DatePickerBaseProps |
selectedShortcutIndex | numberThe currently selected shortcut. If this prop is provided, the component acts in a controlled manner. |
shortcuts | boolean | DateRangeShortcut[] = trueWhether shortcuts to quickly select a range of dates are displayed or not. If true, preset shortcuts will be displayed. If false, no shortcuts will be displayed. If an array is provided, the custom shortcuts will be displayed. |
singleMonthOnly | boolean = falseWhether to show only a single month calendar. |
timePickerProps | TimePickerPropsFurther configure the Inherited from TimePicker that appears beneath the calendar. onChange and value are ignored in favor of the corresponding top-level props on this component.DatePickerBaseProps |
timePrecision | TimePrecisionThe precision of time selection that accompanies the calendar. Passing a Inherited from TimePrecision value (or providing timePickerProps) shows a TimePicker below the calendar. Time is preserved across date changes.DatePickerBaseProps |
value | DateRangeThe currently selected DateRange. If this prop is provided, the component acts in a controlled manner. |