DateRangePicker
Accessible React date range picker for start and end dates on one calendar, with presets, Hijri and Gregorian views, and bounds. Shares the DatePicker core.
DateRangePicker selects a { start, end } range and highlights the days between. It shares the Gregorian/Hijri toggle and calendar core with DatePicker.
When to use
Use DateRangePicker for reporting periods, leave requests, booking windows, or any filter with a start and end. Offer presets such as "Last 30 days" for common ranges. If only one date is needed, use DatePicker.
Both pickers share the Hijri toggle, so the same range works with the Umm al-Qura calendar.
Examples
Props
Props declared by DateRangePicker. Native attributes of the underlying element pass through.
| Prop | Type | Default | Description |
|---|---|---|---|
size | "md" | "lg" | ||
variant | "default" | "filled-lighter" | "filled-darker" | ||
value | DateRange | Currently selected range (controlled). null clears it. | |
defaultValue | DateRange | Initial range when uncontrolled. | |
onChange | (value: DateRange | null) => void | Fires when a complete range is picked, or null when cleared. | |
minValue | Date | Earliest pickable date (inclusive). | |
maxValue | Date | Latest pickable date (inclusive). | |
label | react.ReactNode | Visible label above the trigger. | |
helperText | react.ReactNode | Hint shown below the trigger. Hidden while an error message is showing. | |
errorMessage | react.ReactNode | Message shown below the trigger when error is true. | |
error | boolean | Marks the field invalid - sets aria-invalid and error styling. | |
required | boolean | Marks the field required - adds the asterisk + aria-required. | |
disabled | boolean | Disables the trigger entirely. | |
readOnly | boolean | Read-only: value is shown but not editable (segments + calendar locked). | |
id | string | Caller-supplied id for the field. | |
className | string | Forwarded to the Group (the trigger row), matching Input/Select. | |
aria-label | string | ||
aria-labelledby | string | ||
calendar | CalendarSystem | Calendar system (controlled). Omit to let the user toggle freely. | |
defaultCalendar | CalendarSystem | Initial calendar system when uncontrolled. Defaults to 'gregorian'. | |
onCalendarChange | (calendar: CalendarSystem) => void | Fires whenever the calendar system toggles. | |
showCalendarToggle | boolean | Show the Gregorian↔Hijri toggle inside the popover. Defaults to true, but
is forced off when calendar is controlled. | |
calendarLabels | CalendarLabels | Override the toggle labels. Defaults are locale-aware (English / Arabic). | |
showSecondaryCalendar | boolean | When true, each day cell also shows the other calendar's day number as
small secondary text. Helps cross-reference Hijri↔Gregorian. Default false. |
Accessibility
The range calendar uses the same keyboard model as DatePicker. Arrow keys move, Page Up and Page Down change months, and Enter selects the start and then the end. The selected span is announced.
The field label, helper text, and error follow the TextInput wiring. Presets are ordinary buttons, so they are reachable by keyboard.