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.
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".
| Su | Mo | Tu | We | Th | Fr | Sa |
|---|---|---|---|---|---|---|
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 |
31 | 1 | 2 | 3 | 4 | 5 | 6 |
| Property | Type | Description |
|---|---|---|
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.
Preview
Code
| Su | Mo | Tu | We | Th | Fr | Sa |
|---|---|---|---|---|---|---|
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!
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?ChildrenOrFunction<CalendarRenderProps>;
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).
dir?string;
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.
hidden?boolean;
id?string;
The element's unique identifier. See MDN.
inert?boolean;
lang?string;
maxValue?DateValue | null;
The maximum allowed date that a user may select.
minValue?DateValue | null;
The minimum allowed date that a user may select.
onAnimationEnd?AnimationEventHandler<HTMLDivElement>;
onAnimationEndCapture?AnimationEventHandler<HTMLDivElement>;
onAnimationIteration?AnimationEventHandler<HTMLDivElement>;
onAnimationIterationCapture?AnimationEventHandler<HTMLDivElement>;
onAnimationStart?AnimationEventHandler<HTMLDivElement>;
onAnimationStartCapture?AnimationEventHandler<HTMLDivElement>;
onAuxClick?MouseEventHandler<HTMLDivElement>;
onAuxClickCapture?MouseEventHandler<HTMLDivElement>;
onChange?(value: DateValue) => void;
Handler that is called when the value changes.
onClick?MouseEventHandler<HTMLDivElement>;
onClickCapture?MouseEventHandler<HTMLDivElement>;
onContextMenu?MouseEventHandler<HTMLDivElement>;
onContextMenuCapture?MouseEventHandler<HTMLDivElement>;
onDoubleClick?MouseEventHandler<HTMLDivElement>;
onDoubleClickCapture?MouseEventHandler<HTMLDivElement>;
onFocusChange?(date: CalendarDate) => void;
Handler that is called when the focused date changes.
onGotPointerCapture?PointerEventHandler<HTMLDivElement>;
onGotPointerCaptureCapture?PointerEventHandler<HTMLDivElement>;
onLostPointerCapture?PointerEventHandler<HTMLDivElement>;
onLostPointerCaptureCapture?PointerEventHandler<HTMLDivElement>;
onMouseDown?MouseEventHandler<HTMLDivElement>;
onMouseDownCapture?MouseEventHandler<HTMLDivElement>;
onMouseEnter?MouseEventHandler<HTMLDivElement>;
onMouseLeave?MouseEventHandler<HTMLDivElement>;
onMouseMove?MouseEventHandler<HTMLDivElement>;
onMouseMoveCapture?MouseEventHandler<HTMLDivElement>;
onMouseOut?MouseEventHandler<HTMLDivElement>;
onMouseOutCapture?MouseEventHandler<HTMLDivElement>;
onMouseOver?MouseEventHandler<HTMLDivElement>;
onMouseOverCapture?MouseEventHandler<HTMLDivElement>;
onMouseUp?MouseEventHandler<HTMLDivElement>;
onMouseUpCapture?MouseEventHandler<HTMLDivElement>;
onPointerCancel?PointerEventHandler<HTMLDivElement>;
onPointerCancelCapture?PointerEventHandler<HTMLDivElement>;
onPointerDown?PointerEventHandler<HTMLDivElement>;
onPointerDownCapture?PointerEventHandler<HTMLDivElement>;
onPointerEnter?PointerEventHandler<HTMLDivElement>;
onPointerLeave?PointerEventHandler<HTMLDivElement>;
onPointerMove?PointerEventHandler<HTMLDivElement>;
onPointerMoveCapture?PointerEventHandler<HTMLDivElement>;
onPointerOut?PointerEventHandler<HTMLDivElement>;
onPointerOutCapture?PointerEventHandler<HTMLDivElement>;
onPointerOver?PointerEventHandler<HTMLDivElement>;
onPointerOverCapture?PointerEventHandler<HTMLDivElement>;
onPointerUp?PointerEventHandler<HTMLDivElement>;
onPointerUpCapture?PointerEventHandler<HTMLDivElement>;
onScroll?UIEventHandler<HTMLDivElement>;
onScrollCapture?UIEventHandler<HTMLDivElement>;
onTouchCancel?TouchEventHandler<HTMLDivElement>;
onTouchCancelCapture?TouchEventHandler<HTMLDivElement>;
onTouchEnd?TouchEventHandler<HTMLDivElement>;
onTouchEndCapture?TouchEventHandler<HTMLDivElement>;
onTouchMove?TouchEventHandler<HTMLDivElement>;
onTouchMoveCapture?TouchEventHandler<HTMLDivElement>;
onTouchStart?TouchEventHandler<HTMLDivElement>;
onTouchStartCapture?TouchEventHandler<HTMLDivElement>;
onTransitionCancel?TransitionEventHandler<HTMLDivElement>;
onTransitionCancelCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionEnd?TransitionEventHandler<HTMLDivElement>;
onTransitionEndCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionRun?TransitionEventHandler<HTMLDivElement>;
onTransitionRunCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionStart?TransitionEventHandler<HTMLDivElement>;
onTransitionStartCapture?TransitionEventHandler<HTMLDivElement>;
onWheel?WheelEventHandler<HTMLDivElement>;
onWheelCapture?WheelEventHandler<HTMLDivElement>;
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.translate?"yes" | "no";
value?DateValue | null;
The current value (controlled).
width?WidthProp;
Sets the width of the calendar. You can see allowed tokens here: https://tailwindcss.com/docs/width
Defaults to:
"fit"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: 3 months ago