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.
| 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 |
| 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>.
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.
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.
| 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
accentHeight?string | number;
accumulate?"none" | "sum";
additive?"sum" | "replace";
alignmentBaseline?"alphabetic" |
"hanging" |
"ideographic" |
"mathematical" |
"auto" |
"baseline" |
"before-edge" |
"text-before-edge" |
"middle" |
"central" |
"after-edge" |
"text-after-edge" |
"inherit";
allowReorder?"no" | "yes";
alphabetic?string | number;
amplitude?string | number;
arabicForm?"initial" | "medial" | "terminal" | "isolated";
aria-activedescendant?string;
aria-atomic?Booleanish;
aria-autocomplete?"list" | "none" | "inline" | "both";
aria-braillelabel?string;
aria-brailleroledescription?string;
aria-busy?Booleanish;
aria-checked?boolean | "true" | "false" | "mixed";
aria-colcount?number;
aria-colindex?number;
aria-colindextext?string;
aria-colspan?number;
aria-controls?string;
aria-current?boolean | "true" | "false" | "page" | "step" | "location" | "date" | "time";
aria-describedby?string;
aria-description?string;
aria-details?string;
aria-disabled?Booleanish;
aria-dropeffect?"link" | "none" | "copy" | "execute" | "move" | "popup";
aria-errormessage?string;
aria-expanded?Booleanish;
aria-flowto?string;
aria-grabbed?Booleanish;
aria-haspopup?boolean | "dialog" | "grid" | "listbox" | "menu" | "tree" | "true" | "false";
aria-hidden?Booleanish;
aria-invalid?boolean | "true" | "false" | "grammar" | "spelling";
aria-keyshortcuts?string;
aria-label?string;
aria-labelledby?string;
aria-level?number;
aria-live?"off" | "assertive" | "polite";
aria-modal?Booleanish;
aria-multiline?Booleanish;
aria-multiselectable?Booleanish;
aria-orientation?"horizontal" | "vertical";
aria-owns?string;
aria-placeholder?string;
aria-posinset?number;
aria-pressed?boolean | "true" | "false" | "mixed";
aria-readonly?Booleanish;
aria-relevant?"additions" |
"additions removals" |
"additions text" |
"all" |
"removals" |
"removals additions" |
"removals text" |
"text" |
"text additions" |
"text removals";
aria-required?Booleanish;
aria-roledescription?string;
aria-rowcount?number;
aria-rowindex?number;
aria-rowindextext?string;
aria-rowspan?number;
aria-selected?Booleanish;
aria-setsize?number;
aria-sort?"none" | "ascending" | "descending" | "other";
aria-valuemax?number;
aria-valuemin?number;
aria-valuenow?number;
aria-valuetext?string;
ascent?string | number;
attributeName?string;
attributeType?string;
autoReverse?Booleanish;
azimuth?string | number;
baseFrequency?string | number;
baseProfile?string | number;
baselineShift?string | number;
bbox?string | number;
begin?string | number;
bias?string | number;
by?string | number;
calcMode?string | number;
capHeight?string | number;
children?ReactNode;
className?string;
clip?string | number;
clipPath?string;
clipPathUnits?string | number;
clipRule?string | number;
color?string;
colorInterpolation?string | number;
colorInterpolationFilters?"auto" | "inherit" | "sRGB" | "linearRGB";
colorProfile?string | number;
colorRendering?string | number;
contentScriptType?string | number;
contentStyleType?string | number;
crossOrigin?CrossOrigin;
cursor?CursorProp;
cx?string | number;
cy?string | number;
d?string;
dangerouslySetInnerHTML?{
__html: string | TrustedHTML;
}
decelerate?string | number;
descent?string | number;
diffuseConstant?string | number;
direction?string | number;
display?string | number;
divisor?string | number;
dominantBaseline?"alphabetic" |
"hanging" |
"ideographic" |
"mathematical" |
"auto" |
"text-before-edge" |
"middle" |
"central" |
"text-after-edge" |
"inherit" |
"use-script" |
"no-change" |
"reset-size";
dur?string | number;
dx?string | number;
dy?string | number;
edgeMode?string | number;
elevation?string | number;
enableBackground?string | number;
end?string | number;
exponent?string | number;
externalResourcesRequired?Booleanish;
fill?string;
fillOpacity?string | number;
fillRule?"inherit" | "nonzero" | "evenodd";
filter?string;
filterRes?string | number;
filterUnits?string | number;
floodColor?string | number;
floodOpacity?string | number;
focusable?"auto" | Booleanish;
fontFamily?string;
fontSize?FontSizeProp;
fontSizeAdjust?string | number;
fontStretch?string | number;
fontStyle?string | number;
fontVariant?string | number;
fontWeight?string | number;
format?string | number;
fr?string | number;
from?string | number;
fx?string | number;
fy?string | number;
g1?string | number;
g2?string | number;
glyphName?string | number;
glyphOrientationHorizontal?string | number;
glyphOrientationVertical?string | number;
glyphRef?string | number;
gradientTransform?string;
gradientUnits?string;
hanging?string | number;
horizAdvX?string | number;
horizOriginX?string | number;
href?string;
id?string;
ideographic?string | number;
imageRendering?string | number;
in?string;
in2?string | number;
intercept?string | number;
k?string | number;
k1?string | number;
k2?string | number;
k3?string | number;
k4?string | number;
kernelMatrix?string | number;
kernelUnitLength?string | number;
kerning?string | number;
keyPoints?string | number;
keySplines?string | number;
keyTimes?string | number;
lang?string;
lengthAdjust?string | number;
letterSpacing?string | number;
lightingColor?string | number;
limitingConeAngle?string | number;
local?string | number;
markerEnd?string;
markerHeight?string | number;
markerMid?string;
markerStart?string;
markerUnits?string | number;
markerWidth?string | number;
mask?string;
maskContentUnits?string | number;
maskUnits?string | number;
mathematical?string | number;
max?string | number;
media?string;
method?string;
min?string | number;
mode?string | number;
name?string;
numOctaves?string | number;
offset?string | number;
onAbort?ReactEventHandler<SVGSVGElement>;
onAbortCapture?ReactEventHandler<SVGSVGElement>;
onAnimationEnd?AnimationEventHandler<SVGSVGElement>;
onAnimationEndCapture?AnimationEventHandler<SVGSVGElement>;
onAnimationIteration?AnimationEventHandler<SVGSVGElement>;
onAnimationIterationCapture?AnimationEventHandler<SVGSVGElement>;
onAnimationStart?AnimationEventHandler<SVGSVGElement>;
onAnimationStartCapture?AnimationEventHandler<SVGSVGElement>;
onAuxClick?MouseEventHandler<SVGSVGElement>;
onAuxClickCapture?MouseEventHandler<SVGSVGElement>;
onBeforeInput?InputEventHandler<SVGSVGElement>;
onBeforeInputCapture?FormEventHandler<SVGSVGElement>;
onBeforeToggle?ToggleEventHandler<SVGSVGElement>;
onBlur?FocusEventHandler<SVGSVGElement>;
onBlurCapture?FocusEventHandler<SVGSVGElement>;
onCanPlay?ReactEventHandler<SVGSVGElement>;
onCanPlayCapture?ReactEventHandler<SVGSVGElement>;
onCanPlayThrough?ReactEventHandler<SVGSVGElement>;
onCanPlayThroughCapture?ReactEventHandler<SVGSVGElement>;
onChange?FormEventHandler<SVGSVGElement>;
onChangeCapture?FormEventHandler<SVGSVGElement>;
onClick?MouseEventHandler<SVGSVGElement>;
onClickCapture?MouseEventHandler<SVGSVGElement>;
onCompositionEnd?CompositionEventHandler<SVGSVGElement>;
onCompositionEndCapture?CompositionEventHandler<SVGSVGElement>;
onCompositionStart?CompositionEventHandler<SVGSVGElement>;
onCompositionStartCapture?CompositionEventHandler<SVGSVGElement>;
onCompositionUpdate?CompositionEventHandler<SVGSVGElement>;
onCompositionUpdateCapture?CompositionEventHandler<SVGSVGElement>;
onContextMenu?MouseEventHandler<SVGSVGElement>;
onContextMenuCapture?MouseEventHandler<SVGSVGElement>;
onCopy?ClipboardEventHandler<SVGSVGElement>;
onCopyCapture?ClipboardEventHandler<SVGSVGElement>;
onCut?ClipboardEventHandler<SVGSVGElement>;
onCutCapture?ClipboardEventHandler<SVGSVGElement>;
onDoubleClick?MouseEventHandler<SVGSVGElement>;
onDoubleClickCapture?MouseEventHandler<SVGSVGElement>;
onDrag?DragEventHandler<SVGSVGElement>;
onDragCapture?DragEventHandler<SVGSVGElement>;
onDragEnd?DragEventHandler<SVGSVGElement>;
onDragEndCapture?DragEventHandler<SVGSVGElement>;
onDragEnter?DragEventHandler<SVGSVGElement>;
onDragEnterCapture?DragEventHandler<SVGSVGElement>;
onDragExit?DragEventHandler<SVGSVGElement>;
onDragExitCapture?DragEventHandler<SVGSVGElement>;
onDragLeave?DragEventHandler<SVGSVGElement>;
onDragLeaveCapture?DragEventHandler<SVGSVGElement>;
onDragOver?DragEventHandler<SVGSVGElement>;
onDragOverCapture?DragEventHandler<SVGSVGElement>;
onDragStart?DragEventHandler<SVGSVGElement>;
onDragStartCapture?DragEventHandler<SVGSVGElement>;
onDrop?DragEventHandler<SVGSVGElement>;
onDropCapture?DragEventHandler<SVGSVGElement>;
onDurationChange?ReactEventHandler<SVGSVGElement>;
onDurationChangeCapture?ReactEventHandler<SVGSVGElement>;
onEmptied?ReactEventHandler<SVGSVGElement>;
onEmptiedCapture?ReactEventHandler<SVGSVGElement>;
onEncrypted?ReactEventHandler<SVGSVGElement>;
onEncryptedCapture?ReactEventHandler<SVGSVGElement>;
onEnded?ReactEventHandler<SVGSVGElement>;
onEndedCapture?ReactEventHandler<SVGSVGElement>;
onError?ReactEventHandler<SVGSVGElement>;
onErrorCapture?ReactEventHandler<SVGSVGElement>;
onFocus?FocusEventHandler<SVGSVGElement>;
onFocusCapture?FocusEventHandler<SVGSVGElement>;
onGotPointerCapture?PointerEventHandler<SVGSVGElement>;
onGotPointerCaptureCapture?PointerEventHandler<SVGSVGElement>;
onInput?FormEventHandler<SVGSVGElement>;
onInputCapture?FormEventHandler<SVGSVGElement>;
onInvalid?FormEventHandler<SVGSVGElement>;
onInvalidCapture?FormEventHandler<SVGSVGElement>;
onKeyDown?KeyboardEventHandler<SVGSVGElement>;
onKeyDownCapture?KeyboardEventHandler<SVGSVGElement>;
onKeyPress?KeyboardEventHandler<SVGSVGElement>;
onKeyUp or onKeyDown insteadonKeyPressCapture?KeyboardEventHandler<SVGSVGElement>;
onKeyUpCapture or onKeyDownCapture insteadonKeyUp?KeyboardEventHandler<SVGSVGElement>;
onKeyUpCapture?KeyboardEventHandler<SVGSVGElement>;
onLoad?ReactEventHandler<SVGSVGElement>;
onLoadCapture?ReactEventHandler<SVGSVGElement>;
onLoadStart?ReactEventHandler<SVGSVGElement>;
onLoadStartCapture?ReactEventHandler<SVGSVGElement>;
onLoadedData?ReactEventHandler<SVGSVGElement>;
onLoadedDataCapture?ReactEventHandler<SVGSVGElement>;
onLoadedMetadata?ReactEventHandler<SVGSVGElement>;
onLoadedMetadataCapture?ReactEventHandler<SVGSVGElement>;
onLostPointerCapture?PointerEventHandler<SVGSVGElement>;
onLostPointerCaptureCapture?PointerEventHandler<SVGSVGElement>;
onMouseDown?MouseEventHandler<SVGSVGElement>;
onMouseDownCapture?MouseEventHandler<SVGSVGElement>;
onMouseEnter?MouseEventHandler<SVGSVGElement>;
onMouseLeave?MouseEventHandler<SVGSVGElement>;
onMouseMove?MouseEventHandler<SVGSVGElement>;
onMouseMoveCapture?MouseEventHandler<SVGSVGElement>;
onMouseOut?MouseEventHandler<SVGSVGElement>;
onMouseOutCapture?MouseEventHandler<SVGSVGElement>;
onMouseOver?MouseEventHandler<SVGSVGElement>;
onMouseOverCapture?MouseEventHandler<SVGSVGElement>;
onMouseUp?MouseEventHandler<SVGSVGElement>;
onMouseUpCapture?MouseEventHandler<SVGSVGElement>;
onPaste?ClipboardEventHandler<SVGSVGElement>;
onPasteCapture?ClipboardEventHandler<SVGSVGElement>;
onPause?ReactEventHandler<SVGSVGElement>;
onPauseCapture?ReactEventHandler<SVGSVGElement>;
onPlay?ReactEventHandler<SVGSVGElement>;
onPlayCapture?ReactEventHandler<SVGSVGElement>;
onPlaying?ReactEventHandler<SVGSVGElement>;
onPlayingCapture?ReactEventHandler<SVGSVGElement>;
onPointerCancel?PointerEventHandler<SVGSVGElement>;
onPointerCancelCapture?PointerEventHandler<SVGSVGElement>;
onPointerDown?PointerEventHandler<SVGSVGElement>;
onPointerDownCapture?PointerEventHandler<SVGSVGElement>;
onPointerEnter?PointerEventHandler<SVGSVGElement>;
onPointerLeave?PointerEventHandler<SVGSVGElement>;
onPointerMove?PointerEventHandler<SVGSVGElement>;
onPointerMoveCapture?PointerEventHandler<SVGSVGElement>;
onPointerOut?PointerEventHandler<SVGSVGElement>;
onPointerOutCapture?PointerEventHandler<SVGSVGElement>;
onPointerOver?PointerEventHandler<SVGSVGElement>;
onPointerOverCapture?PointerEventHandler<SVGSVGElement>;
onPointerUp?PointerEventHandler<SVGSVGElement>;
onPointerUpCapture?PointerEventHandler<SVGSVGElement>;
onProgress?ReactEventHandler<SVGSVGElement>;
onProgressCapture?ReactEventHandler<SVGSVGElement>;
onRateChange?ReactEventHandler<SVGSVGElement>;
onRateChangeCapture?ReactEventHandler<SVGSVGElement>;
onReset?FormEventHandler<SVGSVGElement>;
onResetCapture?FormEventHandler<SVGSVGElement>;
onScroll?UIEventHandler<SVGSVGElement>;
onScrollCapture?UIEventHandler<SVGSVGElement>;
onScrollEnd?UIEventHandler<SVGSVGElement>;
onScrollEndCapture?UIEventHandler<SVGSVGElement>;
onSeeked?ReactEventHandler<SVGSVGElement>;
onSeekedCapture?ReactEventHandler<SVGSVGElement>;
onSeeking?ReactEventHandler<SVGSVGElement>;
onSeekingCapture?ReactEventHandler<SVGSVGElement>;
onSelect?ReactEventHandler<SVGSVGElement>;
onSelectCapture?ReactEventHandler<SVGSVGElement>;
onStalled?ReactEventHandler<SVGSVGElement>;
onStalledCapture?ReactEventHandler<SVGSVGElement>;
onSubmit?FormEventHandler<SVGSVGElement>;
onSubmitCapture?FormEventHandler<SVGSVGElement>;
onSuspend?ReactEventHandler<SVGSVGElement>;
onSuspendCapture?ReactEventHandler<SVGSVGElement>;
onTimeUpdate?ReactEventHandler<SVGSVGElement>;
onTimeUpdateCapture?ReactEventHandler<SVGSVGElement>;
onToggle?ToggleEventHandler<SVGSVGElement>;
onTouchCancel?TouchEventHandler<SVGSVGElement>;
onTouchCancelCapture?TouchEventHandler<SVGSVGElement>;
onTouchEnd?TouchEventHandler<SVGSVGElement>;
onTouchEndCapture?TouchEventHandler<SVGSVGElement>;
onTouchMove?TouchEventHandler<SVGSVGElement>;
onTouchMoveCapture?TouchEventHandler<SVGSVGElement>;
onTouchStart?TouchEventHandler<SVGSVGElement>;
onTouchStartCapture?TouchEventHandler<SVGSVGElement>;
onTransitionCancel?TransitionEventHandler<SVGSVGElement>;
onTransitionCancelCapture?TransitionEventHandler<SVGSVGElement>;
onTransitionEnd?TransitionEventHandler<SVGSVGElement>;
onTransitionEndCapture?TransitionEventHandler<SVGSVGElement>;
onTransitionRun?TransitionEventHandler<SVGSVGElement>;
onTransitionRunCapture?TransitionEventHandler<SVGSVGElement>;
onTransitionStart?TransitionEventHandler<SVGSVGElement>;
onTransitionStartCapture?TransitionEventHandler<SVGSVGElement>;
onVolumeChange?ReactEventHandler<SVGSVGElement>;
onVolumeChangeCapture?ReactEventHandler<SVGSVGElement>;
onWaiting?ReactEventHandler<SVGSVGElement>;
onWaitingCapture?ReactEventHandler<SVGSVGElement>;
onWheel?WheelEventHandler<SVGSVGElement>;
onWheelCapture?WheelEventHandler<SVGSVGElement>;
opacity?string | number;
operator?string | number;
order?string | number;
orient?string | number;
orientation?AlignmentProp;
origin?string | number;
overflow?string | number;
overlinePosition?string | number;
overlineThickness?string | number;
paintOrder?string | number;
panose1?string | number;
path?string;
pathLength?string | number;
patternContentUnits?string;
patternTransform?string | number;
patternUnits?string;
pointerEvents?string | number;
points?string;
pointsAtX?string | number;
pointsAtY?string | number;
pointsAtZ?string | number;
preserveAlpha?Booleanish;
preserveAspectRatio?string;
primitiveUnits?string | number;
r?string | number;
radius?string | number;
ref?Ref<SVGSVGElement>;
ref.current to null
(or call the ref with null if you passed a callback ref).
@see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}refX?string | number;
refY?string | number;
renderingIntent?string | number;
repeatCount?string | number;
repeatDur?string | number;
requiredExtensions?string | number;
requiredFeatures?string | number;
restart?string | number;
result?string;
role?AriaRole;
rotate?string | number;
rx?string | number;
ry?string | number;
scale?string | number;
seed?string | number;
shapeRendering?string | number;
slope?string | number;
spacing?string | number;
specularConstant?string | number;
specularExponent?string | number;
speed?string | number;
spreadMethod?string;
startOffset?string | number;
stdDeviation?string | number;
stemh?string | number;
stemv?string | number;
stitchTiles?string | number;
stopColor?string;
stopOpacity?string | number;
strikethroughPosition?string | number;
strikethroughThickness?string | number;
string?string | number;
stroke?string;
strokeDasharray?string | number;
strokeDashoffset?string | number;
strokeLinecap?"inherit" | "butt" | "round" | "square";
strokeLinejoin?"inherit" | "round" | "miter" | "bevel";
strokeMiterlimit?string | number;
strokeOpacity?string | number;
strokeWidth?string | number;
suppressHydrationWarning?boolean;
surfaceScale?string | number;
systemLanguage?string | number;
tabIndex?number;
tableValues?string | number;
target?string;
targetX?string | number;
targetY?string | number;
textAnchor?"end" | "middle" | "inherit" | "start";
textDecoration?string | number;
textLength?string | number;
textRendering?string | number;
to?string | number;
transform?string;
type?string;
u1?string | number;
u2?string | number;
underlinePosition?string | number;
underlineThickness?string | number;
unicode?string | number;
unicodeBidi?string | number;
unicodeRange?string | number;
unitsPerEm?string | number;
vAlphabetic?string | number;
vHanging?string | number;
vIdeographic?string | number;
vMathematical?string | number;
values?string;
vectorEffect?string | number;
version?string;
vertAdvY?string | number;
vertOriginX?string | number;
vertOriginY?string | number;
viewBox?string;
viewTarget?string | number;
visibility?string | number;
widths?string | number;
wordSpacing?string | number;
writingMode?string | number;
x?string | number;
x1?string | number;
x2?string | number;
xChannelSelector?string;
xHeight?string | number;
xlinkActuate?string;
xlinkArcrole?string;
xlinkHref?string;
xlinkRole?string;
xlinkShow?string;
xlinkTitle?string;
xlinkType?string;
xmlBase?string;
xmlLang?string;
xmlSpace?string;
xmlns?string;
xmlnsXlink?string;
y?string | number;
y1?string | number;
y2?string | number;
yChannelSelector?string;
z?string | number;
zoomAndPan?string;
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.