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.

• Header: The top area holding the select boxes and the step buttons.
• Month select box: Jumps directly to a month.
• Year select box: Jumps directly to a year.
• Step buttons: Move to the previous or next month.
• Grid: Holds all selectable dates of the displayed month.
• Date: A single selectable day inside the grid.

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.

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

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.

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.

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.

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.

Quick select presets

Use the presets prop to offer common dates as a one-click list beside the calendar, such as "Today" or "Tomorrow" for a due date. Built-in keys ship with localized labels and correct date math, and custom presets take a label plus a date value or a resolver function. Presets that fall outside minValue/maxValue or land on an unavailable date are disabled.

Calendar accepts the single-date built-ins: today, yesterday and tomorrow. Range keys such as this-week or last-30-days are only available on DateRangePicker and RangeCalendar, where a preset selects a range instead of a single day.

For custom presets, pass value as a function when the date is relative to now (for example "In two weeks"), so it resolves at selection time instead of when the view first rendered. A plain value is right for fixed dates. If you provide several custom presets, give each a unique id: it defaults to the label, so two presets sharing a label would collide.

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.

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