DateRangePicker

A button that picks a start and end date from a two-month range Calendar in a popover.

Example
import { DateRangePicker } from "@elements/ui/date-range-picker";

<DateRangePicker from={trip.from} to={trip.to} />
<DateRangePicker from={stay.from} to={stay.to} min={today} minNights={2} maxNights={14}
                 startName="checkin" endName="checkout" required />

Parts

Part	What it is
DateRangePicker	The picker: a trigger, a Popover with a range Calendar, and two hidden inputs with the ISO ends.
.date-picker-trigger	The button. Shows the range with Intl formatRange; its width holds across every range.
.date-range-picker-content	The popover panel: a dialog named by calendarLabel.
.date-picker-footer	The footer slot under the calendar.
.date-picker-value	The two hidden inputs, named startName and endName, beside the trigger with data-field-input.

Attributes

Attribute	Type	Default	Description
from	ISODate (two-way)	""	Range start, "YYYY-MM-DD".
to	ISODate (two-way)	""	Range end.
open	boolean (two-way)	false	Whether the calendar is showing.
placeholder	string	"Pick a date range"	Shown without a start.
format	Intl.DateTimeFormatOptions	{ month: "short", day: "numeric", year: "numeric" }	Format of each end; the two are joined by Intl formatRange.
locale	string	""	BCP 47 tag for the text and the calendar.
numerals	string	""	Numbering system.
calendar	string	""	An Intl calendar (persian, hebrew, ...) for the months and the text; from and to stay Gregorian ISO dates.
timeZone	string	""	An IANA time zone ("Pacific/Auckland"): today is the date there. Dates stay plain ISO days.
startName	string	""	Form name of the start.
endName	string	""	Form name of the end.
form	string	""	The id of a form elsewhere on the page.
required	boolean	false	Both ends needed for the form to submit.
disabled	boolean	false	Not interactive; not submitted.
readOnly	boolean	false	Shows the range and stays focusable (data-readonly); never opens. Not required, as a native read-only input.
invalid	boolean	false	aria-invalid and the danger border.
size	"sm" | "md" | "lg"	"md"	Height and text from the control tokens.
block	boolean	false	Full width.
label	string	""	Accessible name without a visible label; the range is appended.
calendarLabel	string	"Choose dates"	Names the popover dialog.
icon	boolean	true	A calendar icon in the button.
min	ISODate	""	Earliest date.
max	ISODate	""	Latest date.
minNights	number	0	Shortest range in nights.
maxNights	number	0	Longest range in nights.
disabledDates	Matcher | Matcher[]	false	Days that cannot be picked.
excludeDisabled	boolean	false	A range over a disabled day restarts at the clicked day.
resetOnSelect	boolean	false	A click after a complete range starts a new one.
numberOfMonths	number	2	Months in the popover; one when they do not fit side by side in the viewport.
yearButtons	boolean	false	Previous and next year buttons in the calendar.
help	string	""	Keyboard help announced once focus rests on a day.
pagedNavigation	boolean	false	Navigation moves by numberOfMonths.
modifiers, captionLayout, showOutsideDays, fixedWeeks, showWeekNumber, weekStartsOn, isoWeek, startMonth, endMonth, today, dir	as Calendar	as Calendar	Passed to the Calendar.
month	ISODate	""	The month each open starts on; empty starts on the range start. Browsing never writes it back.
defaultMonth, hidden, navLayout, hideNavigation, disableNavigation, reverseMonths, reverseYears, hideWeekdays, firstWeekContainsDate, broadcastCalendar, animate, labels, formatters	as Calendar	as Calendar	Passed to the Calendar. labels translates the month buttons, dropdowns and day names.
closeOnSelect	boolean	false	Close on the pick that sets the end; the first pick starts the range and keeps it open.
actions	boolean	false	Cancel and OK under the months: OK keeps the picks; Cancel, Escape and an outside press put back the range it opened with.
okLabel, cancelLabel	string	"OK", "Cancel"	The action buttons' text.
side	"top" | "right" | "bottom" | "left" | "inline-start" | "inline-end"	"bottom"	Where the popover opens.
align	"start" | "center" | "end"	"start"	Alignment against the trigger.
modal	boolean	false	Focus trapped in the popover.
class	string	""	Classes on the root.
attrs	Record<string, string | number | boolean | undefined>	{}	Attributes for the button: id, aria-*, data-*.
onRangeChange	(range: { from; to }) => void	() => {}	The picker changed the range.
onOpenChange	(open: boolean) => void	() => {}	The picker opened or closed itself.
onDayClick	(date, modifiers, e) => void	() => {}	From the Calendar.
onMonthChange	(month: ISODate) => void	() => {}	From the Calendar: the shown month changed.

Slots

Slot	Content
footer	Under the calendar in the popover: presets such as Last 7 days, actions.

Keyboard

Keys	Action
Enter / Space	On the button: opens on the range start, else today.
Arrows, PageUp / PageDown, Home / End	Move through the calendar (see Calendar).
Enter / Space on a day	Starts or completes the range.
Escape	Closes and returns focus to the button.

Data attributes

Attribute	Values	On
data-state	"open" | "closed"	root, trigger
data-empty	present without a start	.date-picker-trigger
data-readonly	present with readOnly	.date-picker-trigger

Accessibility

• The trigger has aria-haspopup="dialog", aria-expanded and aria-controls; the popover is a dialog named by calendarLabel.
• Each month is a grid with aria-multiselectable; the range's days carry aria-selected.
• Escape and closeOnSelect return focus to the button.

See also

• Calendar (opens in a new tab): A month grid for picking one date, several dates or a range, with keyboard navigation across months.
• DatePicker (opens in a new tab): A button or text field that picks one date from a Calendar in a popover.
• TimePicker (opens in a new tab): A time of day in the browser's own time field, styled as a control, with steps, limits and suggestions.