Range Calendar

The React Range Calendar component lets users select a contiguous range of dates from an accessible grid of days. Perfect for booking systems, date range filters, trip planners, and any interface where users need to choose a start and end date with full keyboard and screen reader support.

It is built on top of React Aria Components and our Tailwind-styled registry wrapper in range-calendar.tsx. That wrapper adds a polished header with month navigation, a year picker, and accessible day cells with state-driven styling for range visualization.

Installation

npx @tailgrids/cli add range-calendar

Anatomy

Import the building blocks and compose the range calendar.

import {
  RangeCalendar,
  RangeCalendarHeader,
  RangeNavButton,
  RangeCalendarYearPicker,
  RangeCalendarGrid,
  RangeCalendarGridHeader,
  RangeCalendarGridBody,
  RangeCalendarCell
} from "@/components/tailgrids/core/range-calendar";

export default function RangeCalendarExample() {
  return (
    <RangeCalendar aria-label="Choose a date range">
      <RangeCalendarHeader>
        <RangeNavButton slot="previous" />
        <RangeCalendarYearPicker />
        <RangeNavButton slot="next" />
      </RangeCalendarHeader>
      <RangeCalendarGrid>
        <RangeCalendarGridHeader />
        <RangeCalendarGridBody>
          {date => <RangeCalendarCell date={date} />}
        </RangeCalendarGridBody>
      </RangeCalendarGrid>
    </RangeCalendar>
  );
}

Examples

Default Value

Use defaultValue to initialize the range calendar with a pre-selected date range while keeping it uncontrolled.

Controlled

Use value and onChange to fully control the selected date range from React state.

Disabled Dates

Dates outside minValue and maxValue are rendered as disabled cells and are not selectable. This restricts the selectable date range to a specific window.

Unavailable Dates

Use isDateUnavailable for marking specific dates as unavailable, such as weekends or blackout dates. Unlike disabled dates, unavailable dates remain focusable but cannot be selected.

Allow Non-Contiguous Ranges

Use allowNonContiguousRanges to enable selecting date ranges that include unavailable dates.

Validation and Constraints

Combine minValue, maxValue, isDateUnavailable, and isInvalid with a visible helper message to enforce booking constraints and validation rules.

Year Picker

Use RangeCalendarYearPicker component that opens a year menu and updates the focused date. This is a wrapper-specific addition and is not part of React Aria's base API.

Multiple Months

Use visibleDuration to show more than one month at a time in a single calendar.

International Calendar

The Range Calendar component fully supports internationalization. Use the I18nProvider wrapper to localize the calendar for different regions, languages, and calendar systems.

See here for more information.

API Reference

RangeCalendar

The root component wraps React Aria's RangeCalendar but exposes the registry wrapper props below.

RangeCalendarHeader

The header wrapper used for navigation and month/year controls. This is a Tailgrids registry wrapper around a native <header> element, not a React Aria component.

RangeNavButton

The previous and next month buttons. Labels are fixed to Previous month and Next month in the registry wrapper.

RangeCalendarHeading

The centered month and year heading used inside the header row. This is a direct wrapper around React Aria's Heading component.

RangeCalendarYearPicker

An in-header year picker driven by RangeCalendarStateContext. This is a Tailgrids-specific control and is not part of React Aria's public API.

RangeCalendarGrid

Wraps React Aria's CalendarGrid for rendering the date cells.

RangeCalendarGridHeader

Renders the weekday labels for the calendar grid.

RangeCalendarGridBody

Renders the calendar week rows and day cells.

RangeCalendarCell

Renders a date cell for the range calendar.

Data attributes exposed by the cell content:

Visit React Aria's RangeCalendar documentation for more information.

Accessibility

• Keyboard support: Users can navigate between days using arrow keys. They can activate range selection with Enter or Space, and extend the selection by holding Shift while navigating.
• Screen reader support: React Aria provides correct calendar roles, labels, and state announcements for range selection.
• Disabled and unavailable states: Disabled dates cannot be focused or selected, while unavailable dates remain focusable but blocked from selection.
• Range visualization: Selection start and end dates are announced distinctly to clarify range boundaries.
• Year navigation: The custom year picker updates focused calendar state, providing seamless month and year selection.