Calendar

Appointment date, October 2026

Sun	Mon	Tue	Wed	Thu	Fri	Sat
27	28	29	30	1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

import { getLocalTimeZone, today } from "@internationalized/date";
import { Calendar } from "@/components/ui/calendar";

export default function CalendarDemo() {
  return (
    <Calendar
      aria-label="Appointment date"
      defaultValue={today(getLocalTimeZone())}
      className="rounded-lg border bg-card shadow-xs"
    />
  );
}

Installation

$ pnpm dlx shadcn@latest add @desyne/calendar

The CLI installs dependencies and any other components this one uses.

Usage

tsx

import { Calendar, RangeCalendar } from "@/components/ui/calendar";
import { getLocalTimeZone, today } from "@internationalized/date";

tsx

<Calendar aria-label="Due date" defaultValue={today(getLocalTimeZone())} />

Dates are @internationalized/date objects

Values are CalendarDate (or CalendarDateTime / ZonedDateTime) objects from @internationalized/date, not JavaScript Dates. Create them with today(getLocalTimeZone()) or parseDate("2027-03-15"), compare them with a.compare(b), and convert with date.toDate(timeZone) when you need a Date. The calendar follows the user's locale, calendar system and first day of the week automatically.

When to use

Calendar — an always-visible grid, for scheduling screens, booking flows and sidebars where the month context matters.
Date Picker — a compact field that opens this calendar in a popover. The right default inside forms.
Date Field — typed entry only, for dates users already know (birthdays, document dates) where a grid adds nothing.
RangeCalendar — a start and end date. Use Date Range Picker inside forms.

Anatomy

tsx

<Calendar>                 {/* or <RangeCalendar> */}
  <header>
    <Button slot="previous" />
    <Heading />            {/* "March 2027"; visually hidden with dropdowns */}
    {/* captionLayout="dropdown": month <Select> + year <Select> */}
    <Button slot="next" />
  </header>
  <CalendarGrid>           {/* one per visible month */}
    <CalendarGridHeader>   {/* weekday names */}
    <CalendarGridBody>
      <CalendarCell />     {/* one per day */}
    </CalendarGridBody>
  </CalendarGrid>
  <Text slot="errorMessage" />   {/* when errorMessage is set */}
</Calendar>

Part	Renders	Notes
`Calendar`	`<div>`	Single date, or several dates with `selectionMode="multiple"`. `data-slot="calendar"`.
`RangeCalendar`	`<div>`	A contiguous start/end range. `data-slot="range-calendar"`.
Previous / next	`<button>`	Ghost icon `Button`s. Disabled automatically at `minValue` / `maxValue`.
Heading	`<h2 aria-hidden>`	The visible month (or range of months), formatted for the locale. Screen readers get the month from the grid label instead.
Caption selects	`Select` › `<button>` + listbox popover	With `captionLayout` set to a dropdown layout. Labelled with the localized words for month and year. `data-slot="calendar-caption"` on the wrapper.
Grid	`<table role="grid">`	Rendered once per month in `visibleDuration`. Weekdays use the `short` style.
Cell	`<td>` › `<div role="button">`	Each date. All states are exposed as data attributes.
Error message	`<span slot="errorMessage">`	Shown below the grid whenever `errorMessage` is set.

The header, grid and cells are built in, so the only thing you pass is props. For a custom layout, compose React Aria's Calendar parts directly and reuse the cell styles from the source.

Examples

Controlled

Use value and onChange to own the selected date. Format it for display with DateFormatter and the current locale from useLocale().

Delivery date, October 2026

Sun	Mon	Tue	Wed	Thu	Fri	Sat
27	28	29	30	1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

Delivery: Thursday, October 8, 2026

import {
  type CalendarDate,
  DateFormatter,
  getLocalTimeZone,
  today,
} from "@internationalized/date";
import { useState } from "react";
import { useLocale } from "react-aria-components";
import { Calendar } from "@/components/ui/calendar";

export default function CalendarControlled() {
  const { locale } = useLocale();
  const [date, setDate] = useState<CalendarDate | null>(
    today(getLocalTimeZone()).add({ days: 3 }),
  );
  const formatter = new DateFormatter(locale, { dateStyle: "full" });
  return (
    <div className="flex flex-col items-center gap-3">
      <Calendar
        aria-label="Delivery date"
        value={date}
        onChange={setDate}
        className="rounded-lg border bg-card shadow-xs"
      />
      <p className="text-muted-foreground text-sm">
        Delivery:{" "}
        <span className="font-medium text-foreground">
          {date ? formatter.format(date.toDate(getLocalTimeZone())) : "None"}
        </span>
      </p>
    </div>
  );
}

Range

RangeCalendar selects a start and end date. Click (or press Enter) once to set the start, and again to set the end. The value is { start, end }.

Trip dates, October 2026

Sun	Mon	Tue	Wed	Thu	Fri	Sat
27	28	29	30	1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

import { getLocalTimeZone, today } from "@internationalized/date";
import { RangeCalendar } from "@/components/ui/calendar";

export default function CalendarRange() {
  const now = today(getLocalTimeZone());
  return (
    <RangeCalendar
      aria-label="Trip dates"
      defaultValue={{ start: now.add({ days: 2 }), end: now.add({ days: 6 }) }}
      className="rounded-lg border bg-card shadow-xs"
    />
  );
}

Min and max dates

minValue and maxValue disable dates outside the bounds. Disabled dates can't be focused, and the previous and next buttons disable themselves at the edges.

Pickup date, October 2026

Sun	Mon	Tue	Wed	Thu	Fri	Sat
27	28	29	30	1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

Pickup is available for the next three weeks.

import { getLocalTimeZone, today } from "@internationalized/date";
import { Calendar } from "@/components/ui/calendar";

export default function CalendarMinMax() {
  const now = today(getLocalTimeZone());
  return (
    <div className="flex flex-col items-center gap-2">
      <Calendar
        aria-label="Pickup date"
        minValue={now}
        maxValue={now.add({ days: 21 })}
        className="rounded-lg border bg-card shadow-xs"
      />
      <p className="text-muted-foreground text-xs">
        Pickup is available for the next three weeks.
      </p>
    </div>
  );
}

Month and year dropdowns

captionLayout="dropdown" replaces the heading with a month select and a year select, so users can jump years at a time. That's the right choice for dates far from today, such as a birth date. The arrows still page one month at a time.

The year list runs from fromYear to toYear. Without them it uses the years of minValue and maxValue, then falls back to 100 years ago through 10 years ahead. Months outside minValue / maxValue are disabled in the month list.

Date of birth, June 1990

Sun	Mon	Tue	Wed	Thu	Fri	Sat
27	28	29	30	31	1	2
3	4	5	6	7	8	9
10	11	12	13	14	15	16
17	18	19	20	21	22	23
24	25	26	27	28	29	30

import { getLocalTimeZone, today } from "@internationalized/date";
import { Calendar } from "@/components/ui/calendar";

export default function CalendarCaptionDropdown() {
  const now = today(getLocalTimeZone());
  return (
    <Calendar
      aria-label="Date of birth"
      captionLayout="dropdown"
      fromYear={1940}
      maxValue={now}
      defaultFocusedValue={now.set({ year: 1990, month: 6, day: 15 })}
      className="rounded-lg border bg-card shadow-xs"
    />
  );
}

Caption layouts

captionLayout takes four values: label (the default heading), dropdown (both selects), dropdown-months (a month select and the year as text) and dropdown-years (the month as text and a year select). Month names and years follow the locale and calendar system.

Delivery date, October 2026

Sun	Mon	Tue	Wed	Thu	Fri	Sat
27	28	29	30	1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

import { getLocalTimeZone, today } from "@internationalized/date";
import { useState } from "react";
import { Calendar, type CalendarCaptionLayout } from "@/components/ui/calendar";
import { ToggleButton } from "@/components/ui/toggle-button";
import { ToggleButtonGroup } from "@/components/ui/toggle-button-group";

const layouts: CalendarCaptionLayout[] = [
  "label",
  "dropdown",
  "dropdown-months",
  "dropdown-years",
];

export default function CalendarCaptionLayouts() {
  const [layout, setLayout] = useState<CalendarCaptionLayout>("dropdown");
  return (
    <div className="flex flex-col items-center gap-4">
      <ToggleButtonGroup
        aria-label="Caption layout"
        selectionMode="single"
        disallowEmptySelection
        selectedKeys={[layout]}
        onSelectionChange={(keys) =>
          setLayout([...keys][0] as CalendarCaptionLayout)
        }
        variant="segmented"
        size="sm"
      >
        {layouts.map((l) => (
          <ToggleButton key={l} id={l}>
            {l}
          </ToggleButton>
        ))}
      </ToggleButtonGroup>
      <Calendar
        aria-label="Delivery date"
        captionLayout={layout}
        defaultValue={today(getLocalTimeZone())}
        className="rounded-lg border bg-card shadow-xs"
      />
    </div>
  );
}

Dropdowns in a range calendar

RangeCalendar takes the same props. With several visible months, the selects follow the focused month, and picking a month scrolls it into view. Here the window is limited to 11 months, so dropdown-months is enough.

Stay dates, October to November 2026

Sun	Mon	Tue	Wed	Thu	Fri	Sat
27	28	29	30	1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

Sun	Mon	Tue	Wed	Thu	Fri	Sat
1	2	3	4	5	6	7
8	9	10	11	12	13	14
15	16	17	18	19	20	21
22	23	24	25	26	27	28
29	30	1	2	3	4	5

Bookings open 11 months ahead. Jump straight to a month from the header.

import { getLocalTimeZone, today } from "@internationalized/date";
import { RangeCalendar } from "@/components/ui/calendar";

export default function CalendarCaptionRange() {
  const now = today(getLocalTimeZone());
  return (
    <div className="flex flex-col items-center gap-2">
      <RangeCalendar
        aria-label="Stay dates"
        captionLayout="dropdown-months"
        minValue={now}
        maxValue={now.add({ months: 11 })}
        visibleDuration={{ months: 2 }}
        pageBehavior="single"
        className="rounded-lg border bg-card shadow-xs"
      />
      <p className="text-muted-foreground text-xs">
        Bookings open 11 months ahead. Jump straight to a month from the header.
      </p>
    </div>
  );
}

Unavailable dates

isDateUnavailable marks individual dates (holidays, booked days, weekends) as unavailable. Unlike disabled dates, they stay focusable so keyboard and screen reader users can still reach them, and they're struck through.

Meeting date, October 2026

Sun	Mon	Tue	Wed	Thu	Fri	Sat
27	28	29	30	1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

import {
  type DateValue,
  getLocalTimeZone,
  isWeekend,
  today,
} from "@internationalized/date";
import { useLocale } from "react-aria-components";
import { Calendar } from "@/components/ui/calendar";

export default function CalendarUnavailable() {
  const { locale } = useLocale();
  const now = today(getLocalTimeZone());
  // Dates already fully booked.
  const booked = [
    now.add({ days: 3 }),
    now.add({ days: 4 }),
    now.add({ days: 10 }),
  ];
  return (
    <Calendar
      aria-label="Meeting date"
      minValue={now}
      isDateUnavailable={(date: DateValue) =>
        isWeekend(date, locale) || booked.some((d) => d.compare(date) === 0)
      }
      className="rounded-lg border bg-card shadow-xs"
    />
  );
}

Ranges across unavailable dates

By default a range can't include an unavailable date. Set allowsNonContiguousRanges to let the range span them, for example a leave request across a weekend. For RangeCalendar, isDateUnavailable also receives the anchor date (the first date clicked), so you can make availability depend on the start date.

Leave request, October 2026

Sun	Mon	Tue	Wed	Thu	Fri	Sat
27	28	29	30	1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

Span across weekends

import {
  type DateValue,
  getLocalTimeZone,
  isWeekend,
  today,
} from "@internationalized/date";
import { useState } from "react";
import { useLocale } from "react-aria-components";
import { RangeCalendar } from "@/components/ui/calendar";
import { Switch } from "@/components/ui/switch";

export default function CalendarRangeUnavailable() {
  const { locale } = useLocale();
  const [allowWeekends, setAllowWeekends] = useState(false);
  return (
    <div className="flex flex-col items-center gap-3">
      <RangeCalendar
        aria-label="Leave request"
        minValue={today(getLocalTimeZone())}
        isDateUnavailable={(date: DateValue) => isWeekend(date, locale)}
        allowsNonContiguousRanges={allowWeekends}
        className="rounded-lg border bg-card shadow-xs"
      />
      <Switch isSelected={allowWeekends} onChange={setAllowWeekends} size="sm">
        Span across weekends
      </Switch>
    </div>
  );
}

Multiple months

visibleDuration={{ months: 2 }} shows consecutive months side by side (stacked on narrow screens). pageBehavior="single" pages one month at a time instead of a whole visible page.

Campaign dates, October to November 2026

Sun	Mon	Tue	Wed	Thu	Fri	Sat
27	28	29	30	1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

Sun	Mon	Tue	Wed	Thu	Fri	Sat
1	2	3	4	5	6	7
8	9	10	11	12	13	14
15	16	17	18	19	20	21
22	23	24	25	26	27	28
29	30	1	2	3	4	5

import { RangeCalendar } from "@/components/ui/calendar";

export default function CalendarMultipleMonths() {
  return (
    <RangeCalendar
      aria-label="Campaign dates"
      visibleDuration={{ months: 2 }}
      pageBehavior="single"
      className="rounded-lg border bg-card shadow-xs"
    />
  );
}

Multiple dates

selectionMode="multiple" lets users toggle any number of separate dates. The value is a read-only array.

On-call days, October 2026

Sun	Mon	Tue	Wed	Thu	Fri	Sat
27	28	29	30	1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

2 days selected

import {
  type DateValue,
  getLocalTimeZone,
  today,
} from "@internationalized/date";
import { useState } from "react";
import { Calendar } from "@/components/ui/calendar";

export default function CalendarMultipleSelection() {
  const now = today(getLocalTimeZone());
  const [dates, setDates] = useState<readonly DateValue[]>([
    now.add({ days: 1 }),
    now.add({ days: 8 }),
  ]);
  return (
    <div className="flex flex-col items-center gap-3">
      <Calendar
        aria-label="On-call days"
        selectionMode="multiple"
        value={dates}
        onChange={setDates}
        className="rounded-lg border bg-card shadow-xs"
      />
      <p className="text-muted-foreground text-sm">
        {dates.length} {dates.length === 1 ? "day" : "days"} selected
      </p>
    </div>
  );
}

First day of the week

The first weekday comes from the locale (Sunday in en-US, Monday in most of Europe). Override it with firstDayOfWeek.

Sprint start, October 2026

Mon	Tue	Wed	Thu	Fri	Sat	Sun
28	29	30	1	2	3	4
5	6	7	8	9	10	11
12	13	14	15	16	17	18
19	20	21	22	23	24	25
26	27	28	29	30	31	1

import { Calendar } from "@/components/ui/calendar";

export default function CalendarFirstDay() {
  return (
    <Calendar
      aria-label="Sprint start"
      firstDayOfWeek="mon"
      className="rounded-lg border bg-card shadow-xs"
    />
  );
}

Locales and calendar systems

Wrap the calendar in I18nProvider to set a locale. Month and weekday names, digits, text direction and the calendar system all follow it. Add a -u-ca- extension for non-Gregorian calendars (ja-JP-u-ca-japanese, th-TH-u-ca-buddhist). The value you receive is still a CalendarDate in that calendar; convert with toCalendar(date, new GregorianCalendar()) before storing it.

Locale

Date, Oktober 2026

Mo	Di	Mi	Do	Fr	Sa	So
28	29	30	1	2	3	4
5	6	7	8	9	10	11
12	13	14	15	16	17	18
19	20	21	22	23	24	25
26	27	28	29	30	31	1

import { useState } from "react";
import { I18nProvider } from "react-aria-components";
import { Calendar } from "@/components/ui/calendar";
import { Select, SelectItem } from "@/components/ui/select";

const locales = [
  { id: "en-US", name: "English (US)" },
  { id: "de-DE", name: "German" },
  { id: "fr-FR", name: "French" },
  { id: "ar-EG", name: "Arabic (Egypt), RTL" },
  { id: "ja-JP-u-ca-japanese", name: "Japanese imperial calendar" },
  { id: "th-TH-u-ca-buddhist", name: "Thai Buddhist calendar" },
  { id: "hi-IN-u-ca-indian", name: "Indian national calendar" },
];

export default function CalendarLocales() {
  const [locale, setLocale] = useState("de-DE");
  return (
    <div className="flex flex-col items-center gap-4">
      <Select
        label="Locale"
        items={locales}
        selectedKey={locale}
        onSelectionChange={(key) => key && setLocale(String(key))}
        className="w-64"
      >
        {(item) => <SelectItem>{item.name}</SelectItem>}
      </Select>
      <I18nProvider locale={locale}>
        <Calendar
          aria-label="Date"
          className="rounded-lg border bg-card shadow-xs"
        />
      </I18nProvider>
    </div>
  );
}

Controlling the visible month

focusedValue and onFocusChange control which date has focus, and therefore which month is visible. Use them for "Today" or "Jump to" buttons. defaultFocusedValue sets only the initial month.

Release date, March 2027

Sun	Mon	Tue	Wed	Thu	Fri	Sat
28	1	2	3	4	5	6
7	8	9	10	11	12	13
14	15	16	17	18	19	20
21	22	23	24	25	26	27
28	29	30	31	1	2	3

import {
  type CalendarDate,
  getLocalTimeZone,
  parseDate,
  today,
} from "@internationalized/date";
import { useState } from "react";
import { Button } from "@/components/ui/button";
import { Calendar } from "@/components/ui/calendar";

export default function CalendarFocusedValue() {
  const [focused, setFocused] = useState<CalendarDate>(parseDate("2027-03-15"));
  return (
    <div className="flex flex-col items-center gap-3">
      <Calendar
        aria-label="Release date"
        focusedValue={focused}
        onFocusChange={setFocused}
        className="rounded-lg border bg-card shadow-xs"
      />
      <div className="flex gap-2">
        <Button
          size="sm"
          variant="outline"
          onPress={() => setFocused(today(getLocalTimeZone()))}
        >
          Today
        </Button>
        <Button
          size="sm"
          variant="outline"
          onPress={() => setFocused(parseDate("2027-03-15"))}
        >
          Launch day
        </Button>
      </div>
    </div>
  );
}

Validation

Set isInvalid from your own logic and pass errorMessage to explain it. The selected date turns red, and the message is shown below the grid and linked to it for screen readers.

Deployment date, October 2026

Sun	Mon	Tue	Wed	Thu	Fri	Sat
27	28	29	30	1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

Deploys are frozen on weekends. Pick a weekday.

import {
  type CalendarDate,
  getLocalTimeZone,
  isWeekend,
  today,
} from "@internationalized/date";
import { useState } from "react";
import { useLocale } from "react-aria-components";
import { Calendar } from "@/components/ui/calendar";

export default function CalendarValidation() {
  const { locale } = useLocale();
  const [date, setDate] = useState<CalendarDate | null>(() => {
    // Start on the next Saturday so the error is visible.
    let d = today(getLocalTimeZone());
    while (!isWeekend(d, locale)) d = d.add({ days: 1 });
    return d;
  });
  const isInvalid = date !== null && isWeekend(date, locale);
  return (
    <Calendar
      aria-label="Deployment date"
      value={date}
      onChange={setDate}
      isInvalid={isInvalid}
      errorMessage={
        isInvalid
          ? "Deploys are frozen on weekends. Pick a weekday."
          : undefined
      }
      className="max-w-72 rounded-lg border bg-card shadow-xs"
    />
  );
}

Disabled and read-only

isDisabled makes the whole calendar non-interactive. isReadOnly keeps it focusable and navigable, but the value can't change.

Disabled calendar, October 2026

Sun	Mon	Tue	Wed	Thu	Fri	Sat
27	28	29	30	1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

isDisabled

Read-only calendar, October 2026

Sun	Mon	Tue	Wed	Thu	Fri	Sat
27	28	29	30	1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

isReadOnly

import { getLocalTimeZone, today } from "@internationalized/date";
import { Calendar } from "@/components/ui/calendar";

export default function CalendarDisabled() {
  const now = today(getLocalTimeZone());
  return (
    <div className="flex flex-wrap justify-center gap-4">
      <div className="flex flex-col items-center gap-2">
        <Calendar
          aria-label="Disabled calendar"
          isDisabled
          defaultValue={now}
          className="rounded-lg border bg-card shadow-xs"
        />
        <span className="text-muted-foreground text-xs">isDisabled</span>
      </div>
      <div className="flex flex-col items-center gap-2">
        <Calendar
          aria-label="Read-only calendar"
          isReadOnly
          defaultValue={now}
          className="rounded-lg border bg-card shadow-xs"
        />
        <span className="text-muted-foreground text-xs">isReadOnly</span>
      </div>
    </div>
  );
}

Recipes

Booking with a minimum stay

A RangeCalendar with already-booked nights marked unavailable, a minimum-stay rule shown through isInvalid and errorMessage, and a live price summary.

Stay dates, October 2026

Sun	Mon	Tue	Wed	Thu	Fri	Sat
27	28	29	30	1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

Lakeside cabin

$185 / night · 2-night minimum

Check-in: —
Check-out: —
Nights: —

import {
  type CalendarDate,
  DateFormatter,
  type DateValue,
  getLocalTimeZone,
  today,
} from "@internationalized/date";
import { useState } from "react";
import { type RangeValue, useLocale } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { RangeCalendar } from "@/components/ui/calendar";

const NIGHTLY_RATE = 185;
const MIN_NIGHTS = 2;

export default function CalendarRecipeBooking() {
  const { locale } = useLocale();
  const now = today(getLocalTimeZone());
  const booked = [
    { start: now.add({ days: 5 }), end: now.add({ days: 8 }) },
    { start: now.add({ days: 15 }), end: now.add({ days: 17 }) },
  ];
  const [range, setRange] = useState<RangeValue<CalendarDate> | null>(null);

  const nights = range ? range.end.compare(range.start) : 0;
  const tooShort = range !== null && nights < MIN_NIGHTS;
  const fmt = new DateFormatter(locale, { month: "short", day: "numeric" });
  const format = (d: CalendarDate) => fmt.format(d.toDate(getLocalTimeZone()));

  return (
    <div className="flex w-full max-w-md flex-col overflow-hidden rounded-xl border bg-card shadow-xs sm:flex-row">
      <RangeCalendar
        aria-label="Stay dates"
        value={range}
        onChange={setRange}
        minValue={now}
        isDateUnavailable={(date: DateValue) =>
          booked.some(
            (b) => date.compare(b.start) >= 0 && date.compare(b.end) < 0,
          )
        }
        isInvalid={tooShort}
        errorMessage={
          tooShort ? `Minimum stay is ${MIN_NIGHTS} nights.` : undefined
        }
        className="mx-auto"
      />
      <div className="flex flex-1 flex-col gap-3 border-t p-4 sm:border-t-0 sm:border-l">
        <div>
          <p className="font-semibold text-sm">Lakeside cabin</p>
          <p className="text-muted-foreground text-xs">
            ${NIGHTLY_RATE} / night · {MIN_NIGHTS}-night minimum
          </p>
        </div>
        <dl className="grid grid-cols-2 gap-y-1 text-sm">
          <dt className="text-muted-foreground">Check-in</dt>
          <dd className="text-right">{range ? format(range.start) : "—"}</dd>
          <dt className="text-muted-foreground">Check-out</dt>
          <dd className="text-right">{range ? format(range.end) : "—"}</dd>
          <dt className="text-muted-foreground">Nights</dt>
          <dd className="text-right tabular-nums">{nights || "—"}</dd>
        </dl>
        <div className="mt-auto flex items-center justify-between border-t pt-3">
          <span className="font-semibold text-sm tabular-nums">
            ${(nights * NIGHTLY_RATE).toLocaleString()}
          </span>
          <Button size="sm" isDisabled={!range || tooShort}>
            Reserve
          </Button>
        </div>
      </div>
    </div>
  );
}

Appointment scheduler

Pick a weekday within the next six weeks, then a time slot from a ToggleButtonGroup. Changing the date resets the slot.

Appointment date, October 2026

Sun	Mon	Tue	Wed	Thu	Fri	Sat
27	28	29	30	1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

Pick a day

Available times appear once you choose a date. Weekends are closed.

import {
  type CalendarDate,
  DateFormatter,
  getLocalTimeZone,
  isWeekend,
  today,
} from "@internationalized/date";
import { useState } from "react";
import type { Key } from "react-aria-components";
import { useLocale } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { Calendar } from "@/components/ui/calendar";
import { ToggleButton } from "@/components/ui/toggle-button";
import { ToggleButtonGroup } from "@/components/ui/toggle-button-group";

const slots = [
  "09:00",
  "09:30",
  "10:00",
  "11:30",
  "13:00",
  "14:30",
  "15:00",
  "16:30",
];

export default function CalendarRecipeAppointment() {
  const { locale } = useLocale();
  const now = today(getLocalTimeZone());
  const [date, setDate] = useState<CalendarDate | null>(null);
  const [slot, setSlot] = useState<Key | null>(null);
  const fmt = new DateFormatter(locale, {
    weekday: "long",
    month: "long",
    day: "numeric",
  });

  return (
    <div className="flex w-full max-w-lg flex-col overflow-hidden rounded-xl border bg-card shadow-xs sm:flex-row">
      <Calendar
        aria-label="Appointment date"
        value={date}
        onChange={(d) => {
          setDate(d);
          setSlot(null);
        }}
        minValue={now.add({ days: 1 })}
        maxValue={now.add({ days: 45 })}
        isDateUnavailable={(d) => isWeekend(d, locale)}
        className="mx-auto"
      />
      <div className="flex flex-1 flex-col gap-3 border-t p-4 sm:border-t-0 sm:border-l">
        <p className="font-medium text-sm">
          {date ? fmt.format(date.toDate(getLocalTimeZone())) : "Pick a day"}
        </p>
        {date ? (
          <ToggleButtonGroup
            aria-label="Available times"
            variant="spaced"
            size="sm"
            selectionMode="single"
            selectedKeys={slot ? [slot] : []}
            onSelectionChange={(keys) => setSlot([...keys][0] ?? null)}
            className="grid grid-cols-3 gap-1.5 sm:grid-cols-2"
          >
            {slots.map((time) => (
              <ToggleButton key={time} id={time} className="tabular-nums">
                {time}
              </ToggleButton>
            ))}
          </ToggleButtonGroup>
        ) : (
          <p className="text-muted-foreground text-xs">
            Available times appear once you choose a date. Weekends are closed.
          </p>
        )}
        <Button className="mt-auto" isDisabled={!date || !slot}>
          Book 30-minute call
        </Button>
      </div>
    </div>
  );
}

Range presets

Preset buttons set both value and focusedValue, so the calendar jumps to the chosen period. maxValue blocks future dates in a reporting context.

Reporting period, October 2026

Sun	Mon	Tue	Wed	Thu	Fri	Sat
27	28	29	30	1	2	3
4	5	6	7	8	9	10
11	12	13	14	15	16	17
18	19	20	21	22	23	24
25	26	27	28	29	30	31

import {
  type CalendarDate,
  endOfMonth,
  getLocalTimeZone,
  startOfMonth,
  startOfWeek,
  today,
} from "@internationalized/date";
import { useState } from "react";
import { type RangeValue, useLocale } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { RangeCalendar } from "@/components/ui/calendar";

type Range = RangeValue<CalendarDate>;

export default function CalendarRecipePresets() {
  const { locale } = useLocale();
  const now = today(getLocalTimeZone());
  const presets: { label: string; range: Range }[] = [
    { label: "Today", range: { start: now, end: now } },
    {
      label: "Last 7 days",
      range: { start: now.subtract({ days: 6 }), end: now },
    },
    {
      label: "Last 30 days",
      range: { start: now.subtract({ days: 29 }), end: now },
    },
    {
      label: "This week",
      range: { start: startOfWeek(now, locale), end: now },
    },
    { label: "This month", range: { start: startOfMonth(now), end: now } },
    {
      label: "Last month",
      range: {
        start: startOfMonth(now.subtract({ months: 1 })),
        end: endOfMonth(now.subtract({ months: 1 })),
      },
    },
  ];
  const [range, setRange] = useState<Range | null>(presets[1].range);
  const [focused, setFocused] = useState<CalendarDate>(now);

  const isActive = (r: Range) =>
    range !== null &&
    r.start.compare(range.start) === 0 &&
    r.end.compare(range.end) === 0;

  return (
    <div className="flex w-full max-w-md flex-col overflow-hidden rounded-xl border bg-card shadow-xs sm:flex-row">
      <div className="flex gap-1 overflow-x-auto border-b p-2 sm:w-36 sm:flex-col sm:border-r sm:border-b-0">
        {presets.map((p) => (
          <Button
            key={p.label}
            size="sm"
            variant={isActive(p.range) ? "soft" : "ghost"}
            className="shrink-0 justify-start"
            onPress={() => {
              setRange(p.range);
              setFocused(p.range.end);
            }}
          >
            {p.label}
          </Button>
        ))}
      </div>
      <RangeCalendar
        aria-label="Reporting period"
        value={range}
        onChange={setRange}
        focusedValue={focused}
        onFocusChange={setFocused}
        maxValue={now}
        className="mx-auto"
      />
    </div>
  );
}

Accessibility

The calendar is a role="application" group containing one role="grid" table per visible month, labelled by the visible month range.
Give the calendar an accessible name with aria-label or aria-labelledby. It's combined with the visible month when announced.
When the visible month changes, the new month is announced through a live region. Selecting a date or completing a range announces the selection.
Each cell's label includes the full date (weekday, day, month and year), plus "Today" and "selected" where relevant.
Unavailable dates stay focusable and are announced as unavailable. Disabled dates (outside minValue / maxValue) are skipped.
Today is marked with a dot, not just color, and unavailable dates use a strikethrough.
With errorMessage, the message is linked to the calendar with aria-describedby.

Keyboard

Key	Action
`Tab`	Moves between the previous button, next button and the grid
`←` / `→`	Previous / next day (reversed in RTL locales)
`↑` / `↓`	Same day in the previous / next week
`Home` / `End`	First / last day of the month
`Page Up` / `Page Down`	Previous / next month
`Shift`+`Page Up` / `Shift`+`Page Down`	Previous / next year
`Enter` / `Space`	Selects the focused date (in a range: sets the start, then the end)
`Esc`	Cancels a range selection in progress

With a dropdown captionLayout, the month and year selects sit between the previous and next buttons in the tab order. Enter, Space or ↓ opens a select, typing jumps to a matching month or year, and the grid moves to the chosen month.

Styling

Data attributes

On the Calendar / RangeCalendar root:

Attribute	Present when
`data-disabled`	`isDisabled` is true
`data-invalid`	`isInvalid` is true

On each date cell:

Attribute	Present when
`data-selected`	The date is selected (or inside the selected range)
`data-selection-start` / `data-selection-end`	First / last date of a range
`data-today`	The date is today
`data-focused` / `data-focus-visible`	The cell has focus / keyboard focus
`data-hovered` / `data-pressed`	Hovered with a mouse / being pressed
`data-disabled`	Outside `minValue` / `maxValue`, or the calendar is disabled
`data-unavailable`	`isDateUnavailable` returned true
`data-outside-month`	The date belongs to the previous or next month
`data-outside-visible-range`	The date is outside the visible range
`data-invalid`	The date is part of an invalid selection

Slots

`data-slot`	Element
`calendar`	`Calendar` root
`range-calendar`	`RangeCalendar` root
`calendar-caption`	Wrapper around the month / year selects

Customizing

className styles the root (default w-fit p-3). It accepts a function of { isDisabled, isInvalid, state }.
Frame the calendar with classes like rounded-lg border bg-card, as in the examples, or leave it bare inside a card or popover.
Selected dates use the brand color; range middles use accent. Change the theme tokens to restyle every calendar at once.
Cells are size-8. For a different density, copy the component and adjust cellBase.

API Reference

Calendar

Prop

Type

Also accepts every prop of React Aria's Calendar, except children.

RangeCalendar

Accepts every Calendar prop above except selectionMode, with these differences:

Prop

Type

Also accepts every prop of React Aria's RangeCalendar, except children.

Date Picker — this calendar in a popover, attached to a date field.
Date Field — typed, segmented date and time entry.
Toggle Button Group — for time slots next to a calendar.
@internationalized/date — creating, comparing and converting date values.