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, thelabelPlacement
property will beoutside
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 theinnerWrapper
. - input: The date-input element.
- innerWrapper: Wraps the
input
, thestartContent
and theendContent
. - clearButton: The clear button, it is at the end of the input.
- helperWrapper: Wraps the
description
and theerrorMessage
. - 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
ordescription
). 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
Attribute | Type | Description | Default |
---|---|---|---|
label | ReactNode | The content to display as the label. | - |
value | DateValue | The current value of the date input (controlled). | - |
defaultValue | DateValue | The default value of the date input (uncontrolled). | - |
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. | - |
placeholderValue | DateValue | A placeholder time that influences the format of the placeholder shown when no value is selected. Defaults current date at midnight. | - |
minValue | DateValue | The minimum allowed date that a user may select. | - |
maxValue | DateValue | The maximum allowed date that a user may select. | - |
locale | string | The locale to display and edit the value according to. | - |
description | ReactNode | A description for the date input. 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 input. | - |
endContent | ReactNode | Element to be rendered in the right side of the date input. | - |
labelPlacement | inside | outside | outside-left | The position of the label. | inside |
isRequired | boolean | Whether user input is required on the input before form submission. | false |
isReadOnly | boolean | Whether the input can be selected but not changed by the user. | - |
isDisabled | boolean | Whether the input is disabled. | false |
isInvalid | boolean | Whether the input value is invalid. | false |
inputRef | ReactRef<HTMLInputElement | null> | A ref for the hidden input element for HTML form submission. | - |
createCalendar | (name: string) => Calendar | A function that creates a Calendar object for a given calendar identifier. | - |
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 |
disableAnimation | boolean | Whether to disable animations. | false |
classNames | Record<"base"| "label"| "inputWrapper"| "innerWrapper"| "input"| "helperWrapper"| "description"| "errorMessage", string> | Allows to set custom class names for the date input slots. | - |
DateInput Events
Attribute | Type | Description | |
---|---|---|---|
onChange | ((value: ZonedDateTime | CalendarDate | CalendarDateTime) => void) | Handler that is called when the date-input'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. | - |