Calendar

<Calendar aria-label="Appointment date" />

Installation

npx dotui-cli@latest add calendar

Usage

Use Calendar to allow users to select a single date.

import { parseDate } from "@internationalized/date";
import { Calendar } from "@/components/core/calendar";
 
<Calendar
  aria-label="Appointment date"
  defaultValue={parseDate("2025-01-01")}
/>;

import { parseDate } from "@internationalized/date";
import { ChevronLeftIcon, ChevronRightIcon } from "lucide-react";
import { Button } from "@/components/core/button";
import {
  CalendarRoot,
  CalendarHeader,
  CalendarGrid,
  CalendarGridHeader,
  CalendarHeaderCell,
  CalendarGridBody,
  CalendarCell,
} from "@/components/core/calendar";
import { Heading } from "@/registry/ui/default/core/heading";
 
<CalendarRoot
  aria-label="Appointment date"
  defaultValue={parseDate("2025-01-01")}
>
  <CalendarHeader>
    <Button slot="previous">
      <ChevronLeftIcon />
    </Button>
    <Heading />
    <Button slot="next">
      <ChevronRightIcon />
    </Button>
  </CalendarHeader>
  <CalendarGrid>
    <CalendarGridHeader>
      {(day) => <CalendarHeaderCell>{day}</CalendarHeaderCell>}
    </CalendarGridHeader>
    <CalendarGridBody>
      {(date) => <CalendarCell date={date} />}
    </CalendarGridBody>
  </CalendarGrid>
</CalendarRoot>;

Best practices

• An aria-label must be provided to the Calendar for accessibility. If it is labeled by a separate element, an aria-labelledby prop must be provided using the id of the labeling element instead.

Uncontrolled

An initial, uncontrolled value can be provided to the Calendar using the defaultValue prop.

<Calendar aria-label="Appointment date" defaultValue={parseDate("2025-01-01")} />

Controlled

The Calendar component can be controlled by passing the value and onChange props.

const [value, setValue] = React.useState<DateValue>(parseDate('2025-01-01'))
return <Calendar aria-label="Event date" value={value} onChange={setValue} />

Validation

Min and max values

By default, Calendar allows selecting any date. The minValue and maxValue props can also be used to prevent the user from selecting dates outside a certain range.

This example only accepts dates after today.

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

Unavailable dates

Calendar supports marking certain dates as unavailable. These dates cannot be selected by the user and are displayed with a crossed out appearance. The isDateUnavailable prop accepts a callback that is called to evaluate whether each visible date is unavailable.

This example includes multiple unavailable date ranges, e.g. dates when no appointments are available. In addition, all weekends are unavailable. The minValue prop is also used to prevent selecting dates before today.

const now = today(getLocalTimeZone());
const disabledRanges = [
  [now, now.add({ days: 5 })],
  [now.add({ days: 14 }), now.add({ days: 16 })],
  [now.add({ days: 23 }), now.add({ days: 24 })],
];

const { locale } = useLocale();
const isDateUnavailable = (date: DateValue) =>
  isWeekend(date, locale) ||
  disabledRanges.some(
    (interval) => date.compare(interval[0]) >= 0 && date.compare(interval[1]) <= 0
  );

return (
  <Calendar
    minValue={today(getLocalTimeZone())}
    isDateUnavailable={isDateUnavailable}
  />
);

Error message

Calendar tries to avoid allowing the user to select invalid dates in the first place (see Min and max values and Unavailable dates. However, if according to application logic a selected date is invalid, Use isInvalid and errorMessage props.

This example validates that the selected date is a weekday and not a weekend according to the current locale.

const [date, setDate] = React.useState(today(getLocalTimeZone()));
const { locale } = useLocale();
const isInvalid = isWeekend(date, locale);
return (
  <Calendar
    aria-label="Appointment date"
    value={date}
    onChange={setDate}
    isInvalid={isInvalid}
    errorMessage={"We are closed on weekends"}
  />

);

Options

Variant

The variant prop can be used to change the appearance of the Calendar.

<Calendar
  aria-label="Appointment date"
  variant="primary"
  defaultValue={parseDate("2025-01-01")}
/>

Visible months

By default, Calendar displays a single month. The visibleMonths prop allows displaying up to 3 months at a time.

<Calendar aria-label="Appointment date" visibleMonths={2} />

Page behaviour

The pageBehavior prop allows you to control how the calendar navigates between months.

<Calendar aria-label="Appointment date" visibleMonths={2} pageBehavior="single" />

Disabled

The isDisabled boolean prop makes the Calendar disabled. Cells cannot be focused or selected.

<Calendar aria-label="Appointment date" isDisabled />

Read only

The isReadOnly boolean prop makes the Calendar's value immutable. Unlike isDisabled, the Calendar remains focusable.

<Calendar aria-label="Appointment date" isReadOnly value={today(getLocalTimeZone())} />

Composition

If you need to customize things further, you can drop down to the composition level.

<CalendarRoot aria-label="Event date">
  <CalendarHeader>
    <Button slot="previous">
      <ChevronLeftIcon />
    </Button>
    <Heading />
    <Button slot="next">
      <ChevronRightIcon />
    </Button>
  </CalendarHeader>
  <CalendarGrid>
    <CalendarGridHeader>
      {(day) => <CalendarHeaderCell>{day}</CalendarHeaderCell>}
    </CalendarGridHeader>
    <CalendarGridBody>
      {(date) => <CalendarCell date={date} />}
    </CalendarGridBody>
  </CalendarGrid>
</CalendarRoot>

API Reference

Accessibility

Keyboard interactions