Calendar

Choosing date from a calendar.

The <Calendar> is a date selection interface that allows you to choose a date using a calendar view.

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 the year. In the grid section there is a grid of selectable dates.

Anatomy of calendar

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.

Variant
Size
The selected theme does not has any options for "variant" and "size".

calendar, July 2025

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
2
PropertyTypeDescription
variant-The available variants of this component.
size-The available sizes of this component.

Usage

The <Calendar> should be used for experiences where you need to visualize data over an entire month. For most other scenarios, especially where compact input or flexible validation is important, consider using <DatePicker> or <DateField>.

Do

Follow form guidelines for disabled and readonly state.

Accessibility

Calendar cells support keyboard navigation (through arrow keys) and selection (through enter or space), with localized screen reader messages provided to announce changes in selection and the visible date range.

Hint
Keep in mind to use a aria-label when using <Calendar> to ensure screen readers have access to it.

Localization

The <Calendar> itself supports many different calendar systems, all based on the users locale system. You can override the locale system by using the <I18nProvider> from @marigold/components. With that you can use the locale prop and set it to any language system.

Range calendar

With the minValue and maxValue property, you can set a range in which the date can be selected. This is useful if you need to limit the amout of calendar dates to select.

June 2019

26
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
1
2
3
4
5
6

Props

Did you know? You can explore, test, and customize props live in Marigold's storybook. Watch the effects they have in real-time!
View Calendar stories
aria-describedby?
string;
Identifies the element (or elements) that describes the object.
aria-details?
string;
Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-label?
string;
Defines a string value that labels the current element.
aria-labelledby?
string;
Identifies the element (or elements) that labels the current element.
autoFocus?
boolean;
Whether to automatically focus the calendar when it mounts.
Defaults to: 
"false"
children?
ReactNode |
  ((values: CalendarRenderProps & { defaultChildren: ReactNode }) => ReactNode);
The children of the component. A function may be provided to alter the children based on component state.
createCalendar?
(identifier: CalendarIdentifier) => Calendar;
A function to create a new Calendar object for a given calendar identifier. If not provided, the createCalendar function from @internationalized/date will be used.
dateUnavailable?
(date: DateValue) => boolean;
Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
defaultFocusedValue?
DateValue | null;
The date that is focused when the calendar first mounts (uncountrolled).
defaultValue?
DateValue | null;
The default value (uncontrolled).
disabled?
boolean;
Disables the Calendar.
Defaults to: 
"false"
firstDayOfWeek?
"sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat";
The day that starts the week.
focusedValue?
DateValue | null;
Controls the currently focused date within the calendar.
id?
string;
The element's unique identifier. See MDN.
maxValue?
DateValue | null;
The maximum allowed date that a user may select.
minValue?
DateValue | null;
The minimum allowed date that a user may select.
onChange?
(value: DateValue) => void;
Handler that is called when the value changes.
onFocusChange?
(date: CalendarDate) => void;
Handler that is called when the focused date changes.
readOnly?
boolean;
Whether the calendar value is immutable.
Defaults to: 
"false"
slot?
string | null;
A slot name for the component. Slots allow the component to receive props from a parent component. An explicit null value indicates that the local props completely override all props received from a parent.
value?
DateValue | null;
The current value (controlled).
width?
WidthProp;
Width of the calendar.

Alternative Components

Consider the following alternatives for selecting data 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.
Last update: 2 months ago