DateInput

DateInput is a component that allows users to enter and edit date and time values using a keyboard. Each part of a date value is displayed in an individually editable segment.


Installation

npx nextui-cli@latest add date-input
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.

Start & End Content

You can use the startContent and endContent properties to add content to the start and end of the DateInput.

With Description

You can add a description to the input 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.

Controlled

You can use the value and onChange properties to control the input value.

Time Zones

DateInput 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
import {parseZonedDateTime} from "@internationalized/date";

Granularity

The granularity prop allows you to control the smallest unit that is displayed by DateInput 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 @react-aria/i18n
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
import {getLocalTimeZone, parseDate, today} from "@internationalized/date";

International Calendar

DateInput 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 @react-aria/i18n
import {DateValue, now, parseAbsoluteToLocal} from "@internationalized/date";
import {I18nProvider} from "@react-aria/i18n";

Hide Time Zone

When a ZonedDateTime object is provided as the value to DateInput, the time zone abbreviation is displayed by default. However, if this is displayed elsewhere or implicit based on the usecase, it can be hidden using the hideTimeZone option.

@internationalized/date includes functions for parsing strings in multiple formats into ZonedDateTime objects.

npm install @internationalized/date
import {parseZonedDateTime} from "@internationalized/date";

Hourly Cycle

By default, DateInput displays times in either 12 or 24 hour hour format depending on the user's locale. However, this can be overridden using the hourCycle prop if needed for a specific usecase. This example forces DateInput to use 24-hour time, regardless of the locale.

@internationalized/date includes functions for parsing strings in multiple formats into ZonedDateTime objects.

npm install @internationalized/date
import {parseZonedDateTime} from "@internationalized/date";

Slots

  • base: Input wrapper, it handles alignment, placement, and general appearance.
  • label: Label of the date-input, it is the one that is displayed above, inside or left of the date-input.
  • inputWrapper: Wraps the label (when it is inside) and the innerWrapper.
  • input: The date-input element.
  • innerWrapper: Wraps the input, the startContent and the endContent.
  • clearButton: The clear button, it is at the end of the input.
  • helperWrapper: Wraps the description and the errorMessage.
  • description: The description of the date-input.
  • errorMessage: The error message of the date-input.

Data Attributes

DateInput has the following attributes on the base element:

  • data-slot: All slots have this prop. which slot the element represents(e.g. slot).
  • data-invalid: When the date-input is invalid. Based on isInvalid prop.
  • data-required: When the date-input is required. Based on isRequired prop.
  • data-readonly: When the date-input is readonly. Based on isReadOnly prop.
  • data-disabled: When the date-input is disabled. Based on isDisabled prop.
  • data-has-helper: When the date-input has helper text(errorMessage or description). Base on those two props.
  • data-has-start-content: When the date-input has a start content. Base on those startContent prop.
  • data-has-end-content: When the date-input has a end content. Base on those endContent prop.

Accessibility

  • Built with a native <input> element.
  • Visual and ARIA labeling support.
  • Change, clipboard, composition, selection, and input event support.
  • Required and invalid states exposed to assistive technology via ARIA.
  • Support for description and error message help text linked to the input via ARIA.
  • 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.
  • Date segments are editable using an easy to use numeric keypad, and all interactions are accessible using touch-based screen readers.

API

DateInput Props

AttributeTypeDescriptionDefault
labelReactNodeThe content to display as the label.-
valueDateValueThe current value of the date input (controlled).-
defaultValueDateValueThe default value of the date input (uncontrolled).-
variantflat | bordered | faded | underlinedThe variant of the date input.flat
colordefault | primary | secondary | success | warning | dangerThe color of the date input.default
sizesm | md | lgThe size of the date input.md
radiusnone | sm | md | lg | fullThe radius of the date input.-
placeholderValueDateValueA placeholder time that influences the format of the placeholder shown when no value is selected. Defaults current date at midnight.-
minValueDateValueThe minimum allowed date that a user may select.-
maxValueDateValueThe maximum allowed date that a user may select.-
localestringThe locale to display and edit the value according to.-
descriptionReactNodeA description for the date input. Provides a hint such as specific requirements for what to choose.-
errorMessageReactNode | (v: ValidationResult) => ReactNodeAn error message for the date input.-
validate(value: MappedDateValue<DateValue>) => ValidationError | true | null | undefinedValidate 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.-
validationBehaviornative | ariaWhether 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
startContentReactNodeElement to be rendered in the left side of the date input.-
endContentReactNodeElement to be rendered in the right side of the date input.-
labelPlacementinside | outside | outside-leftThe position of the label.inside
isRequiredbooleanWhether user input is required on the input before form submission.false
isReadOnlybooleanWhether the input can be selected but not changed by the user.-
isDisabledbooleanWhether the input is disabled.false
isInvalidbooleanWhether the input value is invalid.false
inputRefReactRef<HTMLInputElement | null>A ref for the hidden input element for HTML form submission.-
createCalendar(name: string) => CalendarA function that creates a Calendar object for a given calendar identifier.-
isDateUnavailable(date: DateValue) => booleanCallback that is called for each date of the calendar. If it returns true, then the date is unavailable.-
autoFocusbooleanWhether the element should receive focus on render.false
hourCycle12 | 24Whether to display the time in 12 or 24 hour format. This is determined by the user's locale.-
granularityday | hour | minute | secondDetermines the smallest unit that is displayed in the date picker. Typically "day" for dates.-
hideTimeZonebooleanWhether to hide the time zone abbreviation.false
shouldForceLeadingZerosbooleanWhether to always show leading zeros in the month, day, and hour fields.true
disableAnimationbooleanWhether to disable animations.false
classNamesRecord<"base"| "label"| "inputWrapper"| "innerWrapper"| "input"| "helperWrapper"| "description"| "errorMessage", string>Allows to set custom class names for the date input slots.-

DateInput Events

AttributeTypeDescription
onChange((value: ZonedDateTime | CalendarDate | CalendarDateTime) => void)Handler that is called when the date-input's value changes.-
onFocus(e: FocusEvent<HTMLInputElement>) => voidHandler that is called when the element receives focus.-
onBlur(e: FocusEvent<HTMLInputElement>) => voidHandler that is called when the element loses focus.-
onFocusChange(isFocused: boolean) => voidHandler that is called when the element's focus status changes.-
onKeyDown(e: KeyboardEvent) => voidHandler that is called when a key is pressed.-
onKeyUp(e: KeyboardEvent) => voidHandler that is called when a key is released.-