DateRangePicker

A range picker whose trigger grows into two months with presets, a stretching range highlight, and an Apply step.

When to use

• Choosing a reporting period, billing window or filter range of whole days.
• When common ranges (last 7 days, this quarter) should be one click away via presets.
• Not for a single date; use DatePicker. For an always-visible month, use Calendar.

Usage

import { DateRangePicker } from "@/components/iris/date-range-picker/date-range-picker";

const [range, setRange] = useState(null);
h(DateRangePicker, {
  label: "Visitors report period",
  value: range, // { start: Date, end: Date } or null
  onChange: setRange, // called on Apply
  weekStartsOn: 1,
  maxDate: new Date(),
});

Props

Prop	Type	Default	Description
value	DateRange | null	–	Controlled { start, end }, inclusive whole days. null for none.
defaultValue	DateRange | null	null	Uncontrolled starting value.
onChange	(range: DateRange) => void	–	Called with the range on Apply.
label	string	"Date range"	Accessible name of the trigger and the dialog.
placeholder	string	"Select dates"	Trigger text with no selection.
presets	{ label; range: (today) => DateRange }[]	Today … Year to date	Preset rail.
minDate / maxDate	Date	–	Selectable bounds.
weekStartsOn	0 | 1	0	0 is Sunday, 1 is Monday.
locale	string	"en-US"	Locale for labels and month titles.
months	"auto" | 1 | 2	"auto"	auto shows two months when the boundary is at least 712px wide.
boundary	() => HTMLElement | null	viewport	Element the panel should stay inside.
className	string	–	Extra class on the root.

Notes

• The selection is a draft until Apply; Cancel, Escape or an outside click discards it.
• Keyboard: Enter/Space opens and picks days; arrows move by day or week; Home/End to week edges; PageUp/PageDown by month (Shift for year); arrows move through presets; Escape closes and returns focus.
• Each month is a labelled grid with full-date day labels and roving tabindex; a polite live region announces the start, then the range and its length.
• The trigger stays disabled until hydration because today's date is unknown on the server.
• Reduced motion drops the grow, slides and gliding range ends in favour of short fades.
• Reads --surface, --line, --accent, --accent-tint, --on-accent, --ink-2, --ink-3, --shadow-resting, --shadow-floating.