Calendar

The React Calendar component lets users pick a date from an accessible grid of days. It is a good fit for scheduling, bookings, reminders, and any interface where date selection needs to stay clear and keyboard-friendly.

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

Installation

npx @tailgrids/cli add calendar

Anatomy

Import the building blocks and compose the calendar.

import {
  Calendar,
  CalendarHeader,
  NavButton,
  CalendarYearPicker,
  CalendarGrid,
  CalendarGridHeader,
  CalendarGridBody,
  CalendarCell
} from "@/components/tailgrids/core/calendar";

export default function CalendarExample() {
  return (
    <Calendar aria-label="Choose a date">
      <CalendarHeader>
        <NavButton slot="previous" />
        <CalendarYearPicker />
        <NavButton slot="next" />
      </CalendarHeader>
      <CalendarGrid>
        <CalendarGridHeader />
        <CalendarGridBody>
          {date => <CalendarCell date={date} />}
        </CalendarGridBody>
      </CalendarGrid>
    </Calendar>
  );
}

Examples

Default Value

Use defaultValue to start the calendar on a selected date while keeping it uncontrolled.

Controlled

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

Disabled

Dates outside minValue and maxValue are rendered as disabled cells and are not selectable.

Unavailable Dates

Use isDateUnavailable for marking specific dates, such as weekends, as unavailable.

Cell Indicator

Because CalendarCell accepts className, you can add a visual marker for selected or important dates without changing the component API.

Validation

Calendar component state can be used to implement custom validation logic according to your application's needs.

Year Picker

Use CalendarYearPicker 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 Calendar API.

International Calendar

The 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

Calendar

The root component wraps React Aria’s Calendar but exposes the registry wrapper props below.

CalendarHeader

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.

NavButton

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

CalendarHeading

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

CalendarYearPicker

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

CalendarGrid

Wraps React Aria’s CalendarGrid for each visible month.

CalendarGridHeader

Renders the weekday labels for a month grid.

CalendarGridBody

Renders the calendar week rows and day cells.

CalendarCell

Renders a date cell using React Aria’s calendar cell state.

Data attributes exposed by the cell content:

Visit React Aria's Calendar documentation for more information.

Accessibility

• Keyboard support: Users can move between days with arrow keys and activate dates with Enter or Space.
• Screen reader support: React Aria provides the correct calendar roles, labels, and state announcements.
• Disabled and unavailable states: Disabled dates cannot be focused or selected, while unavailable dates remain focusable but blocked from selection.
• Year navigation: The custom year picker updates focused calendar state instead of bypassing it.