Calendar

Guidelines React

Github Storybook Markdown Copy for LLM

Import

import {
  UNSTABLE_Calendar,
  UNSTABLE_RangeCalendar,
  UNSTABLE_CalendarGrid,
  UNSTABLE_CalendarCell,
} from "@cfa/react-core";

import { CalendarDate, today, getLocalTimeZone } from "@internationalized/date";

Basic Usage

The Calendar component allows users to select a single date.

Date Highlighting

Highlight specific dates in the calendar using the isDateHighlighted prop. This example highlights the 1st and 15th of each month.

Date Restrictions

Set minimum and maximum dates to restrict selection, or disable specific dates.

Multiple Months

Display multiple months at once using the visibleDuration prop.

RangeCalendar

For selecting date ranges, use the RangeCalendar component.

Import

import {
  UNSTABLE_Calendar as Calendar,
  UNSTABLE_RangeCalendar as RangeCalendar,
  UNSTABLE_CalendarGrid as CalendarGrid,
  UNSTABLE_CalendarCell as CalendarCell,
} from "@cfa/react-core";

import { CalendarDate } from "@internationalized/date";

Basic Range Selection

Subcomponents

import {
  UNSTABLE_Calendar as Calendar,
  UNSTABLE_CalendarGrid as CalendarGrid,
  UNSTABLE_CalendarCell as CalendarCell,
} from "@cfa/react-core";

import { CalendarDate } from "@internationalized/date";

CalendarGrid & CalendarCell

The CalendarGrid component renders the calendar grid structure. It’s typically used internally but can be used for custom calendar layouts.

The CalendarCell component renders individual date cells within the calendar grid.

Props

Visit the

Documentation Site

for the full list of props.

Calendar

Name	Type	Default	Description
errorMessage	string	-	-
isDateHighlighted	(date: T) => boolean	-	-
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	false	Whether to automatically focus the calendar when it mounts.
children	ChildrenOrFunction<CalendarRenderProps>	-	The children of the component. A function may be provided to alter the children based on component state.
className	ClassNameOrFunction<CalendarRenderProps>	'react-aria-Calendar'	The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state.
createCalendar	(identifier: CalendarIdentifier) => Calendar	-	A function to create a new [Calendar](https://react-spectrum.adobe.com/internationalized/date/Calendar.html) object for a given calendar identifier. If not provided, the `createCalendar` function from `@internationalized/date` will be used.
defaultFocusedValue	DateValue	-	The date that is focused when the calendar first mounts (uncontrolled).
defaultValue	DateValue	-	The default value (uncontrolled).
dir	string	-	-
firstDayOfWeek	"sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat"	-	The day that starts the week.
focusedValue	DateValue	-	Controls the currently focused date within the calendar.
hidden	boolean	-	-
id	string	-	The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).
inert	boolean	-	-
isDateUnavailable	(date: DateValue) => boolean	-	Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
isDisabled	boolean	false	Whether the calendar is disabled.
isInvalid	boolean	-	Whether the current selection is invalid according to application logic.
isReadOnly	boolean	false	Whether the calendar value is immutable.
lang	string	-	-
maxValue	DateValue	-	The maximum allowed date that a user may select.
minValue	DateValue	-	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: MappedDateValue<T>) => 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>	-	-
pageBehavior	PageBehavior	visible	Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
render	DOMRenderFunction<"div", CalendarRenderProps>	-	Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: * You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). * Only a single root DOM element can be rendered (no fragments). * You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
selectionAlignment	"start" | "center" | "end"	'center'	Determines the alignment of the visible months on initial render based on the current selection or current date if there is no selection.
slot	string	-	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.
style	StyleOrFunction<CalendarRenderProps>	-	The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state.
translate	"yes" | "no"	-	-
value	DateValue	-	The current value (controlled).
visibleDuration	DateDuration	{months: 1}	The amount of days that will be displayed at once. This affects how pagination works.

RangeCalendar

CalendarGrid

CalendarCell