Date Range Picker

Date Range Picker combines two DateInputs and a RangeCalendar popover to allow users to enter or select a date and time range.


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

If you pass the isRequired property to the input, it will have a danger asterisk at the end of the label and the input will be required.

Variants

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.

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 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.

With Time Fields

DateRangePicker automatically includes time fields when a CalendarDateTime or ZonedDateTime object is provided as the value.

Selector Icon

You can use the selector to add content to the start and end of the date-range-picker.

Controlled

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

Time Zones

DateRangePicker 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 DateRangePicker 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

DateRangePicker 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";

Unavailable Dates

DateRangePicker 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 @react-aria/i18n
import {today, isWeekend, getLocalTimeZone} from "@internationalized/date";
import {useLocale} from "@react-aria/i18n";

Non Contiguous

The allowsNonContiguousRanges prop enables a range to be selected even if there are unavailable dates in the middle. The value emitted in the onChange event will still be a single range with a start and end property, but unavailable dates will not be displayed as selected. It is up to applications to split the full selected range into multiple as needed for business logic.

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

npm install @internationalized/date @react-aria/i18n
import {today, isWeekend, getLocalTimeZone} from "@internationalized/date";
import {useLocale} from "@react-aria/i18n";

Presets

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

npm install @internationalized/date @react-aria/i18n
import {
DateValue,
now,
startOfWeek,
startOfMonth,
getLocalTimeZone,
} from "@internationalized/date";
import {useLocale, useDateFormatter} from "@react-aria/i18n";

Slots

  • base: base element. it handles alignment, placement, and general appearance.
  • label: Label of the date-range-picker, it is the one that is displayed above, inside or left of the date-input.
  • calendar: The calendar element.
  • selectorButton: Selector button element.
  • selectorIcon: Selector icon element.
  • popoverContent: The calendar popover element.
  • calendarContent: The calendar's content element.
  • inputWrapper: Wraps the label (when it is inside) and the innerWrapper.
  • input: The input element.
  • segment: The segment element.
  • separator: The separator element.
  • bottomContent: The bottom content element.
  • timeInputWrapper: The wrapper element for the input element.
  • helperWrapper: Wraps the description and the errorMessage.
  • description: The description of the date-input.
  • errorMessage: The error message of the date-input.

Custom Styles

You can customize the DateRangePicker component by passing custom Tailwind CSS classes to the component slots.

Data Attributes

DateRangePicker has the following attributes on the base element:

  • data-slot: All slots have this prop. which slot the element represents(e.g. canlendar).
  • data-open: Indicates if the calendar popover is open.
  • data-invalid: When the date-range-picker is invalid. Based on isInvalid prop.
  • data-required: When the date-range-picker is required. Based on isRequired prop.
  • data-readonly: When the date-range-picker is readonly. Based on isReadOnly prop.
  • data-disabled: When the date-range-picker is disabled. Based on isDisabled prop.
  • data-has-start-content: When the date-range-picker has a start content. Base on those startContent prop.
  • data-has-end-content: When the date-range-picker has a end content. Base on those endContent prop.
  • data-has-multiple-months: When the date-range-picker's visibleMonth is more than 2.

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 date ranges 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, date ranges can be selected by dragging over dates in the calendar using a touch screen, 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

DateRangePicker Props

AttributeTypeDescriptionDefault
labelReactNodeThe content to display as the label.-
valueRangeValue<CalendarDate | CalendarDateTime | ZonedDateTime> | undefined | nullThe current value of the date-range-picker (controlled).-
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.-
minValueRangeValue<CalendarDate | CalendarDateTime | ZonedDateTime> | undefined | nullThe minimum value of the date-range-picker.-
maxValueRangeValue<CalendarDate | CalendarDateTime | ZonedDateTime> | undefined | nullThe maximum value of the date-range-picker.-
defaultValuestring | undefinedThe default value of the date-range-picker (uncontrolled).-
placeholderValueZonedDateTime | CalendarDate | CalendarDateTime | undefined | nullThe placeholder of the date-range-picker.-
descriptionReactNodeA description for the date-range-picker. Provides a hint such as specific requirements for what to choose.-
errorMessageReactNode | (v: ValidationResult) => ReactNodeAn error message for the date input.-
validate(value: RangeValue<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-range-picker.-
endContentReactNodeElement to be rendered in the right side of the date-range-picker.-
startNamestringThe name of the start date input element, used when submitting an HTML form. See MDN-
endNamestringThe name of the end date input element, used when submitting an HTML form. See MDN-
labelPlacementinside | outside | outside-leftThe position of the label.inside
isOpenbooleanWhether the date picker popover is open.-
defaultOpenbooleanWhether the date picker popover is open by default.false
isRequiredbooleanWhether user input is required on the date-range-picker before form submission.false
isReadOnlybooleanWhether the date-range-picker can be selected but not changed by the user.
isDisabledbooleanWhether the date-range-picker is disabled.false
isInvalidbooleanWhether the date-range-picker is invalid.false
selectorIconReactNodeThe icon to toggle the date picker popover. Usually a calendar icon.
pageBehaviorsingle | visibleControls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.visible
visibleMonthsnumberThe number of months to display at once. Up to 3 months are supported.1
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
allowsNonContiguousRangesbooleanWhen combined with isDateUnavailable, determines whether non-contiguous ranges, i.e. ranges containing unavailable dates, may be selected.false
shouldForceLeadingZerosbooleanWhether to always show leading zeros in the month, day, and hour fields.true
calendarWidthnumberThe width to be applied to the calendar component.256
CalendarTopContentReactNodeTop content to be rendered in the calendar component.
CalendarBottomContentReactNodeBottom content to be rendered in the calendar component.
allowsNonContiguousRangesbooleanenables a range to be selected even if there are unavailable dates in the middlefalse
popoverPropsPopoverPropsProps to be passed to the popover component.{ placement: "bottom", triggerScaleOnOpen: false, offset: 13 }
selectorButtonPropsButtonPropsProps to be passed to the selector button component.{ size: "sm", variant: "light", radius: "full", isIconOnly: true }
calendarPropsCalendarPropsProps to be passed to the selector button component.{ size: "sm", variant: "light", radius: "full", isIconOnly: true }
timeInputPropsTimeInputPropsProps to be passed to the time input component.{ size: "sm", variant: "light", radius: "full", isIconOnly: true }
disableAnimationbooleanWhether to disable all animations in the date picker. Including the DateInput, Button, Calendar, and Popover.false
classNamesRecord<"base" | "selectorButton" | "selectorIcon" | "popoverContent" | "calendar" | "calendarContent" | "timeInputLabel" | "timeInput", string>Allows to set custom class names for the date-range-picker slots.-

DateRangePicker Events

AttributeTypeDescription
onChange((value: RangeValue<CalendarDate | CalendarDateTime | ZonedDateTime>) => void) | undefinedHandler that is called when the date-range-picker's value changes.-
onOpenChange(isOpen: boolean) => voidHandler that is called when the date picker popover is opened or closed.-
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.-