Calendar

The <Calendar> is a date selection interface that allows you to choose a date using a visual calendar view. It displays a month grid with navigable months and years, making it easy to browse and select specific dates.

Anatomy

The <Calendar> consists of a header and a grid section. Inside of the header there are two select lists, one for a month and one for a year. In the grid section there is a grid of selectable dates.

Appearance

The appearance of a component can be customized using the variant and size props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.

Usage

The <Calendar> should be used for experiences where you need to visualize and select dates over an entire month, such as event scheduling or availability views. For most other scenarios, especially where compact input or flexible validation is important, consider using <DatePicker> or <DateField>.

Basic Usage (uncontrolled)

This example shows a basic <Calendar> without any special props. The component manages its own state internally.

import { Calendar } from '@marigold/components';export default () => <Calendar aria-label="Event date" />;

Controlled

The value and onChange props can be used to control the selected date externally. This is useful when you need to display or process the selected date elsewhere in your application.

Selected Date: Day: 7 Month: 8 Year: 2025

import type { DateValue } from '@internationalized/date';import { CalendarDate } from '@internationalized/date';import { useState } from 'react';import { Calendar, Stack } from '@marigold/components';export default () => {  const [value, setValue] = useState<DateValue>(new CalendarDate(2025, 8, 7));  return (    <Stack space={3}>      <Calendar        aria-label="Event date"        value={value}        onChange={newValue => setValue(newValue!)}      />      <pre>        <strong>Selected Date: </strong>        {`Day: ${value.day} Month: ${value.month} Year: ${value.year}`}      </pre>    </Stack>  );};

Min/Max Values

The minValue and maxValue props restrict the selectable date range. Dates outside the specified range are automatically disabled, preventing the user from selecting invalid dates.

Always disable dates that cannot be selected, such as past dates for a future booking, or dates outside a valid business range. This prevents user errors and communicates constraints visually.

import { CalendarDate } from '@internationalized/date';import { Calendar } from '@marigold/components';export default () => (  <Calendar    aria-label="Event date"    minValue={new CalendarDate(2025, 6, 5)}    maxValue={new CalendarDate(2025, 6, 20)}  />);

Unavailable Dates

The dateUnavailable prop accepts a callback function that is called for each date in the calendar. If it returns true, the date is marked as unavailable. This is useful for blocking out specific dates like weekends or holidays.

import type { DateValue } from '@internationalized/date';import { isWeekend } from '@internationalized/date';import { useLocale } from '@react-aria/i18n';import { Calendar } from '@marigold/components';export default () => {  const { locale } = useLocale();  return (    <Calendar      aria-label="Appointment date"      dateUnavailable={(date: DateValue) => isWeekend(date, locale)}    />  );};

Multiple Months

Use the visibleDuration prop to display multiple months at once. This is helpful for date range selection or when users need to see a broader time span. Up to 3 months are supported.

import { Calendar } from '@marigold/components';export default () => (  <Calendar aria-label="Event date" visibleDuration={{ months: 2 }} />);

When users need to select dates far in the past or future (such as a birth date or historical event), a calendar grid forces tedious month-by-month navigation. Even with multiple months visible, this does not solve the problem. In those cases, a <DateField> or <DatePicker> is more efficient.

Accessibility

The <Calendar> is built on React Aria and provides full keyboard navigation and screen reader support out of the box.

Keyboard navigation:

• Arrow keys: Move focus between dates
• Page Up/Down: Navigate to previous/next month
• Home/End: Move to the first/last day of the current month
• Enter/Space: Select the focused date

Localization

The <Calendar> supports many different calendar systems based on the user's locale. You can override the locale by wrapping the calendar with the <I18nProvider> from @marigold/components and setting the locale prop to any supported locale string.

import { I18nProvider } from '@marigold/components';import { Calendar } from '@marigold/components';export default () => (  <I18nProvider locale="de-DE">    <Calendar aria-label="Veranstaltungsdatum" />  </I18nProvider>);

Props

Calendar

Alternative components

Consider the following alternatives for selecting dates tailored to different user needs and input methods.

• DatePicker: The <DatePicker> allows users to input a date directly as text, in addition to selecting one, and offers more robust validation and error messaging capabilities.

• DateField: Use the <DateField> if you need to only use text input to select a date.

Related