# DateRangePicker

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

```ehtml 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](calendar): A month grid for picking one date, several dates or a range, with keyboard navigation across months.
- [DatePicker](date-picker): A button or text field that picks one date from a Calendar in a popover.
- [TimePicker](time-picker): A time of day in the browser's own time field, styled as a control, with steps, limits and suggestions.