Calendar Range Picker

Props

• label: string (required) -- accessible name describing the picker purpose, applied via aria-label
• children: slot (required) -- the calendar grid content including date cells and navigation controls

Keyboard Interactions

None built-in -- the consumer should implement date cell navigation (arrow keys), selection (Enter/Space), and range extension (Shift + arrow keys or Shift + click) as appropriate.

ARIA

• role="application" -- indicates that the widget manages its own keyboard interactions, overriding standard screen reader navigation
• aria-label={label} -- provides an accessible name for the calendar range picker

When to Use

• Use for selecting a start and end date visually on a calendar grid
• Use when the date range is relative or the user needs visual context of the dates, such as booking systems, travel planners, or analytics dashboards
• Use when users benefit from seeing the span of selected days highlighted across the calendar
• Use when the interaction requires richer keyboard navigation than a simple date input

When Not to Use

• Do not use when users know exact dates -- use two DateInput fields instead for a compact entry
• Do not use for single date selection -- use CalendarTable or DateInput
• Do not use when screen space is very limited -- use DateInput with a popover calendar instead

Headless

This component provides a <div> with role="application" and aria-label as a container for calendar-based range selection, with zero visual styling. The consumer is responsible for all rendering of the calendar grid, date cells, range highlighting, navigation controls, and all CSS including layout, colors, selected state, and hover effects.

Styles

The consumer provides all CSS styling. The component renders with a .calendar-range-picker class for targeting. No default styles are included — this is a fully headless component.

Testing

• Verify the component renders a <div> element with class calendar-range-picker
• Verify role="application"` -- indicates that the widget manages its own keyboard interactions, overriding standard screen reader navigation
• Verify aria-label={label}` -- provides an accessible name for the calendar range picker
• Verify pass-through attributes are applied

Advice

• Designers: Clearly highlight the selected range with a distinct background color spanning from the start date to the end date. Show hover previews as the user moves toward the end date.
• Developers: Implement keyboard navigation for date cells (arrow keys), selection (Enter/Space), and range extension (Shift+click or Shift+arrow). Since role="application" overrides screen reader navigation, ensure all keyboard interactions are fully implemented.

Implementation Notes

• Renders a <div> with role="application" to support rich keyboard interactions beyond standard navigation
• Consumer provides all calendar grid rendering, date selection logic, and range highlighting
• The role="application" signals to screen readers that the widget handles its own keyboard interactions
• Accepts ...restProps for forwarding additional attributes to the container

Related components

• date-range — paired start and end date inputs
• date-field — a structured field for entering date components
• calendar-table — a calendar table interactive grid for managing dates, days, etc. <table>

References

• WAI-ARIA Application Role: https://www.w3.org/TR/wai-aria-1.2/#application
• WAI-ARIA Grid Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/grid/