Skip to content

DatePicker

A date picker combines a DateField and a Calendar popover to allow users to enter or select a date and time value.

Import

import { DatePicker as DatePicker } from "@cfa/react-core";
import { UNSTABLE_DateField } from "@cfa/react-core";

Live Editor

Examples

Basic Usage

The most common way to use DatePicker is with the composite component.

Composable Usage

For more control, use the individual subcomponents.

Controlled Usage

Control the date value from a parent component.

Date Ranges

Set minimum and maximum dates to restrict selection.

Disabled Dates

Disable specific dates using the isDateUnavailable prop. The example below disables the weekends.

Date Highlighting

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

Validation States

The DatePicker component supports different validation states.

Date and Time

Use different granularities for date and time selection.

Calendar Customizations

Customize the calendar display by changing the first day of week and the number of visible months.

Compact Variant

For smaller spaces, use the compact variant.

Props

Visit the Documentation Site for the full list of props.

NameTypeDefaultDescription
compactboolean--
descriptionstring--
errorMessagestring | ((validation: ValidationResult) => string)--
isDateHighlighted(date: T) => boolean--
isInvalidboolean-Whether the input value is invalid.
isReadOnlyboolean-Whether the input can be selected but not changed by the user.
labelstring--
styleCSSProperties-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.
aria-describedbystring-Identifies the element (or elements) that describes the object.
aria-detailsstring-Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-labelstring-Defines a string value that labels the current element.
aria-labelledbystring-Identifies the element (or elements) that labels the current element.
autoCompletestring-Describes the type of autocomplete functionality the input should provide if any. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete).
autoFocusboolean-Whether the element should receive focus on render.
childrenChildrenOrFunction<DatePickerRenderProps>-The children of the component. A function may be provided to alter the children based on component state.
classNameClassNameOrFunction<DatePickerRenderProps>'react-aria-DatePicker'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.
defaultOpenboolean-Whether the overlay is open by default (uncontrolled).
defaultValueDateValue-The default value (uncontrolled).
dirstring--
firstDayOfWeek"sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat"-The day that starts the week.
formstring-The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form).
granularityGranularity-Determines the smallest unit that is displayed in the date picker. By default, this is `"day"` for dates, and `"minute"` for times.
hiddenboolean--
hideTimeZonebooleanfalseWhether to hide the time zone abbreviation.
hourCycle12 | 24-Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale.
idstring-The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).
inertboolean--
isDateUnavailable(date: DateValue) => boolean-Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
isDisabledboolean-Whether the input is disabled.
isOpenboolean-Whether the overlay is open by default (controlled).
isRequiredboolean-Whether user input is required on the input before form submission.
langstring--
maxValueDateValue-The maximum allowed date that a user may select.
minValueDateValue-The minimum allowed date that a user may select.
namestring-The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname).
onAnimationEndAnimationEventHandler<HTMLDivElement>--
onAnimationEndCaptureAnimationEventHandler<HTMLDivElement>--
onAnimationIterationAnimationEventHandler<HTMLDivElement>--
onAnimationIterationCaptureAnimationEventHandler<HTMLDivElement>--
onAnimationStartAnimationEventHandler<HTMLDivElement>--
onAnimationStartCaptureAnimationEventHandler<HTMLDivElement>--
onAuxClickMouseEventHandler<HTMLDivElement>--
onAuxClickCaptureMouseEventHandler<HTMLDivElement>--
onBlur(e: FocusEvent<Element, Element>) => void-Handler that is called when the element loses focus.
onChange(value: MappedDateValue<T>) => void-Handler that is called when the value changes.
onClickMouseEventHandler<HTMLDivElement>--
onClickCaptureMouseEventHandler<HTMLDivElement>--
onContextMenuMouseEventHandler<HTMLDivElement>--
onContextMenuCaptureMouseEventHandler<HTMLDivElement>--
onDoubleClickMouseEventHandler<HTMLDivElement>--
onDoubleClickCaptureMouseEventHandler<HTMLDivElement>--
onFocus(e: FocusEvent<Element, Element>) => void-Handler that is called when the element receives focus.
onFocusChange(isFocused: boolean) => void-Handler that is called when the element's focus status changes.
onGotPointerCapturePointerEventHandler<HTMLDivElement>--
onGotPointerCaptureCapturePointerEventHandler<HTMLDivElement>--
onKeyDown(e: KeyboardEvent) => void-Handler that is called when a key is pressed.
onKeyUp(e: KeyboardEvent) => void-Handler that is called when a key is released.
onLostPointerCapturePointerEventHandler<HTMLDivElement>--
onLostPointerCaptureCapturePointerEventHandler<HTMLDivElement>--
onMouseDownMouseEventHandler<HTMLDivElement>--
onMouseDownCaptureMouseEventHandler<HTMLDivElement>--
onMouseEnterMouseEventHandler<HTMLDivElement>--
onMouseLeaveMouseEventHandler<HTMLDivElement>--
onMouseMoveMouseEventHandler<HTMLDivElement>--
onMouseMoveCaptureMouseEventHandler<HTMLDivElement>--
onMouseOutMouseEventHandler<HTMLDivElement>--
onMouseOutCaptureMouseEventHandler<HTMLDivElement>--
onMouseOverMouseEventHandler<HTMLDivElement>--
onMouseOverCaptureMouseEventHandler<HTMLDivElement>--
onMouseUpMouseEventHandler<HTMLDivElement>--
onMouseUpCaptureMouseEventHandler<HTMLDivElement>--
onOpenChange(isOpen: boolean) => void-Handler that is called when the overlay's open state changes.
onPointerCancelPointerEventHandler<HTMLDivElement>--
onPointerCancelCapturePointerEventHandler<HTMLDivElement>--
onPointerDownPointerEventHandler<HTMLDivElement>--
onPointerDownCapturePointerEventHandler<HTMLDivElement>--
onPointerEnterPointerEventHandler<HTMLDivElement>--
onPointerLeavePointerEventHandler<HTMLDivElement>--
onPointerMovePointerEventHandler<HTMLDivElement>--
onPointerMoveCapturePointerEventHandler<HTMLDivElement>--
onPointerOutPointerEventHandler<HTMLDivElement>--
onPointerOutCapturePointerEventHandler<HTMLDivElement>--
onPointerOverPointerEventHandler<HTMLDivElement>--
onPointerOverCapturePointerEventHandler<HTMLDivElement>--
onPointerUpPointerEventHandler<HTMLDivElement>--
onPointerUpCapturePointerEventHandler<HTMLDivElement>--
onScrollUIEventHandler<HTMLDivElement>--
onScrollCaptureUIEventHandler<HTMLDivElement>--
onTouchCancelTouchEventHandler<HTMLDivElement>--
onTouchCancelCaptureTouchEventHandler<HTMLDivElement>--
onTouchEndTouchEventHandler<HTMLDivElement>--
onTouchEndCaptureTouchEventHandler<HTMLDivElement>--
onTouchMoveTouchEventHandler<HTMLDivElement>--
onTouchMoveCaptureTouchEventHandler<HTMLDivElement>--
onTouchStartTouchEventHandler<HTMLDivElement>--
onTouchStartCaptureTouchEventHandler<HTMLDivElement>--
onTransitionCancelTransitionEventHandler<HTMLDivElement>--
onTransitionCancelCaptureTransitionEventHandler<HTMLDivElement>--
onTransitionEndTransitionEventHandler<HTMLDivElement>--
onTransitionEndCaptureTransitionEventHandler<HTMLDivElement>--
onTransitionRunTransitionEventHandler<HTMLDivElement>--
onTransitionRunCaptureTransitionEventHandler<HTMLDivElement>--
onTransitionStartTransitionEventHandler<HTMLDivElement>--
onTransitionStartCaptureTransitionEventHandler<HTMLDivElement>--
onWheelWheelEventHandler<HTMLDivElement>--
onWheelCaptureWheelEventHandler<HTMLDivElement>--
pageBehaviorPageBehaviorvisibleControls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
placeholderValueDateValue-A placeholder date that influences the format of the placeholder shown when no value is selected. Defaults to today's date at midnight.
renderDOMRenderFunction<"div", DatePickerRenderProps>-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.
shouldCloseOnSelectboolean | (() => boolean)trueDetermines whether the date picker popover should close automatically when a date is selected.
shouldForceLeadingZerosboolean-Whether to always show leading zeros in the month, day, and hour fields. By default, this is determined by the user's locale.
slotstring-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"--
validate(value: MappedDateValue<T>) => true | ValidationError-A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead.
validationBehavior"native" | "aria"'native'Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
valueDateValue-The current value (controlled).
visibleDurationDateDuration{months: 1}The amount of days that will be displayed at once. This affects how pagination works.