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, the labelPlacement property will be outside 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

DatePicker Events