DatePicker
DatePickers combine a DateInput and a Calendar popover to allow users to enter or select a date and time value.
Installation
npx nextui-cli@latest add date-picker
The above command is for individual installation only. You may skip this step if @nextui-org/react
is already installed globally.
Import
Usage
Disabled
Read Only
Required
Variants
Label Placements
You can change the position of the label by setting the labelPlacement
property to inside
, outside
or outside-left
.
Note: If the
label
is not passed, thelabelPlacement
property will beoutside
by default.
With Description
You can add a description to the date-picker by passing the description
property.
With Error Message
You can combine the isInvalid
and errorMessage
properties to show an invalid input.
You can also pass an error message as a function. This allows for dynamic error message handling based on the ValidationResult.
With Month and Year Pickers
You can show month and year pickers in the calendar popover by setting the showMonthAndYearPickers
property to true
. However, passing a number greater than 1 to the visibleMonths
prop will disable this feature.
With Time Fields
Selector Icon
You can use the selector
to add content to the start and end of the date-picker.
Selector Button Placement
You can change the position of the selector button by setting the selectorButtonPlacement
property to start
or end
.
Controlled
You can use the value
and onChange
properties to control the input value.
Time Zones
DatePicker is time zone aware when a ZonedDateTime
object is provided as the value. In this case, the time zone abbreviation is displayed,
and time zone concerns such as daylight saving time are taken into account when the value is manipulated.
@internationalized/date includes functions for parsing strings
in multiple formats into ZonedDateTime
objects.
npm install @internationalized/date@3.5.5
import {parseZonedDateTime} from "@internationalized/date";
Granularity
The granularity prop allows you to control the smallest unit that is displayed by DatePicker By default,
the value is displayed with "day" granularity (year, month, and day),
and CalendarDateTime
and ZonedDateTime
values are displayed with "minute" granularity.
@internationalized/date includes functions for parsing strings
in multiple formats into ZonedDateTime
objects.
npm install @internationalized/date@3.5.5 @react-aria/i18n@3.12.2
import {DateValue, now, parseAbsoluteToLocal} from "@internationalized/date";import {useDateFormatter} from "@react-aria/i18n";
Min Date And Max Date
The minValue and maxValue props can also be used to ensure the value is within a specific range.
@internationalized/date includes functions for parsing strings
in multiple formats into ZonedDateTime
objects.
npm install @internationalized/date@3.5.5
import {getLocalTimeZone, parseDate, today} from "@internationalized/date";
International Calendar
DatePicker supports selecting dates in many calendar systems used around the world, including Gregorian, Hebrew, Indian, Islamic, Buddhist, and more. Dates are automatically displayed in the appropriate calendar system for the user's locale. The calendar system can be overridden using the Unicode calendar locale extension, passed to the I18nProvider component.
@internationalized/date includes functions for parsing strings
in multiple formats into ZonedDateTime
objects.
npm install @internationalized/date@3.5.5 @react-aria/i18n@3.12.2
import {DateValue, now, parseAbsoluteToLocal} from "@internationalized/date";import {I18nProvider} from "@react-aria/i18n";
Unavailable Dates
DatePicker supports marking certain dates as unavailable. These dates cannot be selected by the user and are displayed with a crossed out appearance in the calendar. In the date field, an invalid state is displayed if a user enters an unavailable date.
@internationalized/date includes functions for parsing strings
in multiple formats into ZonedDateTime
objects.
npm install @internationalized/date@3.5.5 @react-aria/i18n@3.12.2
import {today, isWeekend, getLocalTimeZone} from "@internationalized/date";import {useLocale} from "@react-aria/i18n";
Visible Months
By default, the calendar popover displays a single month. The visibleMonths
prop allows displaying up to 3 months at a time, if screen space permits.
Page Behavior
By default, when pressing the next or previous buttons, pagination will advance by the visibleMonths
value. This behavior can be changed to page by single months instead, by setting pageBehavior
to single
.
Preset
@internationalized/date includes functions for parsing strings
in multiple formats into ZonedDateTime
objects.
npm install @internationalized/date@3.5.5 @react-aria/i18n@3.12.2
import {DateValue,now,useLocale,startOfWeek,startOfMonth,useDateFormatter,getLocalTimeZone,} from "@internationalized/date";import {I18nProvider} from "@react-aria/i18n";
Slots
- base: Input wrapper, it handles alignment, placement, and general appearance.
- selectorButton: Selector button element.
- selectorIcon: Selector icon element.
- popoverContent: The calendar popover element.
- calendar: The calendar element.
- calendarContent: The calendar's content element.
- timeInputLabel: The time-input component's label element.
- timeInput: The time-input component element.
Data Attributes
DatePicker
has the following attributes on the base
element:
- data-slot:
All slots have this prop. which slot the element represents(e.g.
calendar
). - data-open: Indicates if the calendar popover is open.
- data-invalid:
When the date-picker is invalid. Based on
isInvalid
prop. - data-required:
When the date-picker is required. Based on
isRequired
prop. - data-readonly:
When the date-picker is readonly. Based on
isReadOnly
prop. - data-disabled:
When the date-picker is disabled. Based on
isDisabled
prop.
Accessibility
- Each date and time unit is displayed as an individually focusable and editable segment, which allows users an easy way to edit dates using the keyboard, in any date format and locale.
- Users can also open a calendar popover to select dates in a standard month grid.
- Localized screen reader messages are included to announce when the selection and visible date range change.
- Date segments are editable using an easy to use numeric keypad, and all interactions are accessible using touch-based screen readers.
- Integrates with HTML forms, supporting required, minimum and maximum values, unavailable dates, custom validation functions, realtime validation, and server-side validation errors
API
DatePicker Props
Attribute | Type | Description | Default |
---|---|---|---|
label | ReactNode | The content to display as the label. | - |
value | ZonedDateTime | CalendarDate | CalendarDateTime | undefined | null | The current value of the date-picker (controlled). | - |
variant | flat | bordered | faded | underlined | The variant of the date input. | flat |
color | default | primary | secondary | success | warning | danger | The color of the date input. | default |
size | sm | md | lg | The size of the date input. | md |
radius | none | sm | md | lg | full | The radius of the date input. | - |
defaultValue | string | The default value of the date-picker (uncontrolled). | - |
placeholderValue | ZonedDateTime | CalendarDate | CalendarDateTime | undefined | null | The placeholder of the date-picker. | - |
description | ReactNode | A description for the date-picker. Provides a hint such as specific requirements for what to choose. | - |
errorMessage | ReactNode | (v: ValidationResult) => ReactNode | An error message for the date input. | - |
validate | (value: MappedDateValue<DateValue>) => ValidationError | true | null | undefined | Validate input values when committing (e.g. on blur), returning error messages for invalid values. Display validation errors upon form submission if validationBehavior is set to native . For real-time validation, use the isInvalid prop. | - |
validationBehavior | native | aria | 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. | aria |
startContent | ReactNode | Element to be rendered in the left side of the date-picker. | - |
endContent | ReactNode | Element to be rendered in the right side of the date-picker. | - |
labelPlacement | inside | outside | outside-left | The position of the label. | inside |
isRequired | boolean | Whether user input is required on the date-picker before form submission. | false |
isReadOnly | boolean | Whether the date-picker can be selected but not changed by the user. | |
isDisabled | boolean | Whether the date-picker is disabled. | false |
isInvalid | boolean | Whether the date-picker is invalid. | false |
visibleMonths | number | The number of months to display at once. Up to 3 months are supported. Passing a number greater than 1 will disable the showMonthAndYearPickers prop. | 1 |
selectorIcon | ReactNode | The icon to toggle the date picker popover. Usually a calendar icon. | |
pageBehavior | PageBehavior | Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration. | visible |
calendarWidth | number | The width to be applied to the calendar component. | 256 |
CalendarTopContent | ReactNode | Top content to be rendered in the calendar component. | |
isDateUnavailable | ((date: DateValue) => boolean) | Callback that is called for each date of the calendar. If it returns true, then the date is unavailable. | |
autoFocus | boolean | Whether the element should receive focus on render. | false |
hourCycle | 12 | 24 | Whether to display the time in 12 or 24 hour format. This is determined by the user's locale. | - |
granularity | day | hour | minute | second | Determines the smallest unit that is displayed in the date picker. Typically "day" for dates. | - |
hideTimeZone | boolean | Whether to hide the time zone abbreviation. | false |
shouldForceLeadingZeros | boolean | Whether to always show leading zeros in the month, day, and hour fields. | true |
CalendarBottomContent | ReactNode | Bottom content to be rendered in the calendar component. | |
showMonthAndYearPickers | boolean | undefined | Whether the calendar should show month and year pickers. | false |
popoverProps | PopoverProps | undefined | Props to be passed to the popover component. | { placement: "bottom", triggerScaleOnOpen: false, offset: 13 } |
selectorButtonProps | ButtonProps | undefined | Props to be passed to the selector button component. | { size: "sm", variant: "light", radius: "full", isIconOnly: true } |
selectorButtonPlacement | start | end | The position of the selector button. | end |
calendarProps | CalendarProps | undefined | Props to be passed to the selector button component. | { size: "sm", variant: "light", radius: "full", isIconOnly: true } |
timeInputProps | TimeInputProps | Props to be passed to the time input component. | { size: "sm", variant: "light", radius: "full", isIconOnly: true } |
disableAnimation | boolean | Whether to disable all animations in the date picker. Including the DateInput, Button, Calendar, and Popover. | false |
classNames | Record<"base" | "selectorButton" | "selectorIcon" | "popoverContent" | "calendar" | "calendarContent" | "timeInputLabel" | "timeInput", string> | Allows to set custom class names for the date-picker slots. | - |
dateInputClassNames | Record<"base"| "label"| "inputWrapper"| "innerWrapper"| "input"| "helperWrapper"| "description"| "errorMessage", string> | Allows to set custom class names for the date input slots. | - |
DatePicker Events
Attribute | Type | Description | |
---|---|---|---|
onChange | ((value: ZonedDateTime | CalendarDate | CalendarDateTime) => void) | undefined | Handler that is called when the date-picker's value changes. | - |
onFocus | (e: FocusEvent<HTMLInputElement>) => void | Handler that is called when the element receives focus. | - |
onBlur | (e: FocusEvent<HTMLInputElement>) => void | Handler that is called when the element loses focus. | - |
onFocusChange | (isFocused: boolean) => void | Handler that is called when the element's focus status changes. | - |
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. | - |