This component is in beta
While fully functional, the API may change depending on user feedback. We
encourage you to try it out and share your experience, as this will help
us improve component functionality and stability.
The Date Range Picker component allows users to select a start and end date, typically through text fields with calendar popovers.
- Collect a date range in forms or filters (e.g., booking reservations, event scheduling, report date filtering).
- When users need to define a bounded period and visual calendar selection improves accuracy.
- Pair with time inputs if time-of-day precision is required.
- Dual segmented fields: Separate start and end date fields with a separator (e.g., “to” or ”–”).
- Popover calendar: Single or dual calendar view triggered from fields or button.
- Inline with validation: Prevent invalid ranges (e.g., end date before start date) or include error states for invalid ranges.
- For single date selection; use Date Picker instead.
- For open-ended ranges (e.g., “from date onward”); use single Date Field.
- For large or complex range selection requiring advanced controls; consider custom solutions.
- When space is severely constrained on mobile without responsive adaptation.
| Variant | Use Case |
|---|
| Day (default) | Standard day-level granularity |
| Month | Coarse selection for month-based ranges |
| With Time | Include time selection for precise datetime ranges |
| Element | Description |
|---|
| Label | Text describing the overall range purpose. |
| Start Field | Segmented or text field for start date entry. |
| End Field | Segmented or text field for end date entry. |
| Separator | Visual or textual divider between start and end (e.g., “to” or ”–”). |
| Trigger | Optional button or field interaction to open calendar popover. |
| Popover/Dialog | Container for the range calendar(s). |
| Range Calendar | One or two month grids for selecting start and end dates. |
| Preset Buttons | Optional quick-select range options. |
- Calendar icon on trigger or fields for affordance.
| State | Description | Visual Indicators |
|---|
| Default | Default interactive state | Neutral border and text |
| Hover | Cursor over object | Subtle border or background change |
| Focus | Keyboard focus (visible on Tab or arrow key navigation) or on click | High-contrast focus ring |
| Disabled | Non-interactive | Grayed out, reduced opacity |
| Invalid | Validation error (e.g., end before start) | Red border, error icon/message |
- Use clear labels (e.g., “Date range”, “Check-in to check-out”).
- Individual fields: “Start date” and “End date” if separately labeled.
- Placeholder: Locale-appropriate format (e.g., “mm/dd/yyyy”).
- Error messages: Specific (e.g., “End date must be after start date”).
- Presets: Concise and descriptive (e.g., “Today”, “Last 30 days”).
- Use
role="group" with aria-labelledby for the overall picker.
- Field supports
aria-label describing the range (e.g., “Date range”).
- Calendar grid uses
role="grid" with aria-selected for highlighted range.
- Announce selected range and validation errors via live region or description.
- Support
aria-required, aria-invalid, and aria-errormessage.
Support standard keyboard navigation
- Tab: Focus fields or trigger; move between start/end fields.
- Enter/Space: Open popover from trigger or focused field.
- Arrow keys: Navigate calendar grid; select dates.
- Page Up/Down: Switch months.
- Home/End: First/last day of month.
- Escape: Close popover.
