Calendar

Import

import { Calendar } from "@thenamespace/uikit";

Usage

"use client";

import {Calendar} from "@thenamespace/uikit";

export function Basic() {

Anatomy

import { Calendar } from "@thenamespace/uikit";

export default () => (
  <Calendar aria-label="Event date">
    <Calendar.Header>
      <Calendar.Heading />
      <Calendar.NavButton slot="previous" />
      <Calendar.NavButton slot="next" />
    </Calendar.Header>
    <Calendar.Grid>
      <Calendar.GridHeader>
        {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
      </Calendar.GridHeader>
      <Calendar.GridBody>
        {(date) => <Calendar.Cell date={date} />}
      </Calendar.GridBody>
    </Calendar.Grid>
  </Calendar>
);

Year Picker

Calendar.YearPickerTrigger, Calendar.YearPickerGrid, and their body/cell subcomponents provide an integrated year navigation pattern.

"use client";

import {Calendar} from "@thenamespace/uikit";

export function YearPicker() {

Default Value

"use client";

import {Calendar} from "@thenamespace/uikit";
import {parseDate} from "@internationalized/date";

Controlled

Use controlled value and focusedValue for external state coordination and custom shortcuts.

"use client";

import type {CalendarDate} from "@internationalized/date";

import {Button, ButtonGroup, Calendar, Description} from "@thenamespace/uikit";

Min and Max Dates

"use client";

import {Calendar, Description} from "@thenamespace/uikit";
import {getLocalTimeZone, today} from "@internationalized/date";

Unavailable Dates

Use isDateUnavailable to block dates such as weekends, holidays, or booked slots.

"use client";

import type {DateValue} from "@internationalized/date";

import {Calendar, Description} from "@thenamespace/uikit";

Weeks in Month

Set weeksInMonth to a fixed value (for example, 6) to keep the grid height stable when navigating between months. Use with care in non-Gregorian locales, similar to firstDayOfWeek.

"use client";

import {Calendar, Description} from "@thenamespace/uikit";

export function WeeksInMonth() {

Week View

Set visibleDuration={{ weeks: n }} to show one or more weeks at a time. Navigation advances by the visible week range. Use pageBehavior="single" to move one week at a time when showing multiple weeks.

"use client";

import {Calendar, Label, ListBox, Select} from "@thenamespace/uikit";
import {useState} from "react";

Day View

Set visibleDuration={{ days: n }} to show a rolling window of consecutive days. Navigation advances by the visible day range. Use pageBehavior="single" to move one day at a time when showing multiple days.

"use client";

import {Calendar, Label, ListBox, Select} from "@thenamespace/uikit";
import {useState} from "react";

Multiple Selection

Set selectionMode="multiple" to let users select several dates. value, defaultValue, and onChange use an array of dates.

"use client";

import type {DateValue} from "@internationalized/date";

import {Calendar, Description} from "@thenamespace/uikit";

Disabled

"use client";

import {Calendar, Description} from "@thenamespace/uikit";
import {getLocalTimeZone, today} from "@internationalized/date";

Read Only

"use client";

import {Calendar, Description} from "@thenamespace/uikit";
import {getLocalTimeZone, today} from "@internationalized/date";

Focused Value

Programmatically control which date is focused using focusedValue and onFocusChange.

"use client";

import type {DateValue} from "@internationalized/date";

import {Button, Calendar, Description} from "@thenamespace/uikit";

Cell Indicators

You can customize Calendar.Cell children and use Calendar.CellIndicator to display metadata like events.

"use client";

import {Calendar} from "@thenamespace/uikit";
import {getLocalTimeZone, isToday} from "@internationalized/date";

Multiple Months

Render multiple grids with visibleDuration and offset for booking and planning experiences. Use Calendar.Heading with an offset (for example, offset={{ months: 1 }}) in each column header to label that month.

"use client";

import {Calendar} from "@thenamespace/uikit";

export function MultipleMonths() {

International Calendars

By default, Calendar displays dates using the calendar system for the user's locale. You can override this by wrapping your Calendar with I18nProvider and setting the Unicode calendar locale extension.

The example below shows the Indian calendar system:

"use client";

import {Calendar} from "@thenamespace/uikit";
import {getLocalTimeZone, today} from "@internationalized/date";
import {I18nProvider} from "react-aria-components";

Note: The onChange event always returns a date in the same calendar system as the value or defaultValue (Gregorian if no value is provided), regardless of the displayed locale. This ensures your application logic works consistently with a single calendar system while still displaying dates in the user's preferred format.

Custom Navigation Icons

Pass children to Calendar.NavButton to replace the default chevron icons.

"use client";

import {Calendar} from "@thenamespace/uikit";

export function CustomIcons() {

Real-World Example

"use client";

import type {CalendarDate, DateValue} from "@internationalized/date";

import {Button, Calendar} from "@thenamespace/uikit";

Custom Styles

"use client";

import {Calendar} from "@thenamespace/uikit";

export function CustomStyles() {

Styling

Passing Tailwind CSS classes

import { Calendar } from "@thenamespace/uikit";

function CustomCalendar() {
  return (
    <Calendar
      aria-label="Custom calendar"
      className="w-72 rounded-2xl border border-border bg-surface p-3 shadow-sm"
    >
      <Calendar.Header className="pb-3">
        <Calendar.Heading className="text-default" />
        <Calendar.NavButton slot="previous" className="text-default" />
        <Calendar.NavButton slot="next" className="text-default" />
      </Calendar.Header>
      <Calendar.Grid>
        <Calendar.GridHeader>
          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
        </Calendar.GridHeader>
        <Calendar.GridBody>
          {(date) => <Calendar.Cell date={date} />}
        </Calendar.GridBody>
      </Calendar.Grid>
    </Calendar>
  );
}

Customizing the component classes

@layer components {
  .calendar {
    @apply w-72 rounded-2xl border border-border bg-surface p-3 shadow-sm;
  }

  .calendar__heading {
    @apply text-sm font-semibold text-default-700;
  }

  .calendar__cell[data-selected="true"] {
    @apply bg-accent text-accent-foreground;
  }
}

CSS Classes

Calendar uses these classes in packages/styles/components/calendar.css and packages/styles/components/calendar-year-picker.css:

• .calendar - Root container.
• .calendar__header - Header row containing nav buttons and heading.
• .calendar__heading - Current month label.
• .calendar__nav-button - Previous/next navigation controls.
• .calendar__grid - Main day grid.
• .calendar__grid-header - Weekday header row wrapper.
• .calendar__grid-body - Date rows wrapper.
• .calendar__header-cell - Weekday header cell.
• .calendar__cell - Interactive day cell.
• .calendar__cell-indicator - Dot indicator inside a day cell.
• .calendar-year-picker__trigger - Year picker toggle button.
• .calendar-year-picker__trigger-heading - Heading text inside year picker trigger.
• .calendar-year-picker__trigger-indicator - Indicator icon inside year picker trigger.
• .calendar-year-picker__year-grid - Overlay grid of selectable years.
• .calendar-year-picker__year-cell - Individual year option.

Interactive States

Calendar supports both pseudo-classes and React Aria data attributes:

• Selected: [data-selected="true"]
• Today: [data-today="true"]
• Unavailable: [data-unavailable="true"]
• Outside month: [data-outside-month="true"]
• Hovered: :hover or [data-hovered="true"]
• Pressed: :active or [data-pressed="true"]
• Focus visible: :focus-visible or [data-focus-visible="true"]
• Disabled: :disabled or [data-disabled="true"]

API Reference

Calendar Props

Calendar inherits all props from React Aria Calendar.

Composition Parts

Year Picker Parts

Year picker subcomponents inherit formatting props from React Aria useCalendarHeading and useCalendarYearPicker.

Calendar.Cell Render Props

When Calendar.Cell children is a function, React Aria render props are available:

For a complete list of supported calendar systems and their identifiers, see:

• React Aria Calendar Implementations
• React Aria International Calendars

Related packages

• @internationalized/date — date types (CalendarDate, CalendarDateTime, ZonedDateTime) and utilities used by all date components
• I18nProvider — override locale for a subtree
• useLocale — read the current locale and layout direction