HeroUI
Getting Started
Components
Releases

DateRangePickerNew

Composable date range picker built on React Aria DateRangePicker with DateField and RangeCalendar composition

FigmaStorybookReact AriaSourceStyles source

Import

import { DateField, DateRangePicker, Label, RangeCalendar } from '@heroui/react';

Usage

Trip dates
"use client";

import {DateField, DateRangePicker, Label, RangeCalendar} from "@heroui/react";

export function Basic() {

Anatomy

DateRangePicker follows a composition-first API. Compose DateField and RangeCalendar explicitly to control structure and styling.

import {DateField, DateRangePicker, Label, RangeCalendar} from '@heroui/react';

export default () => (
  <DateRangePicker>
    <Label />
    <DateField.Group>
      <DateField.Input slot="start">
        {(segment) => <DateField.Segment segment={segment} />}
      </DateField.Input>
      <DateRangePicker.RangeSeparator />
      <DateField.Input slot="end">
        {(segment) => <DateField.Segment segment={segment} />}
      </DateField.Input>
      <DateField.Suffix>
        <DateRangePicker.Trigger>
          <DateRangePicker.TriggerIndicator />
        </DateRangePicker.Trigger>
      </DateField.Suffix>
    </DateField.Group>
    <DateRangePicker.Popover>
      <RangeCalendar aria-label="Choose trip dates">
        <RangeCalendar.Header>
          <RangeCalendar.YearPickerTrigger>
            <RangeCalendar.YearPickerTriggerHeading />
            <RangeCalendar.YearPickerTriggerIndicator />
          </RangeCalendar.YearPickerTrigger>
          <RangeCalendar.NavButton slot="previous" />
          <RangeCalendar.NavButton slot="next" />
        </RangeCalendar.Header>
        <RangeCalendar.Grid>
          <RangeCalendar.GridHeader>
            {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}
          </RangeCalendar.GridHeader>
          <RangeCalendar.GridBody>{(date) => <RangeCalendar.Cell date={date} />}</RangeCalendar.GridBody>
        </RangeCalendar.Grid>
      </RangeCalendar>
    </DateRangePicker.Popover>
  </DateRangePicker>
)

Controlled

Trip dates
Current value: 2026-02-19 -> 2026-02-23
"use client";

import type {DateValue} from "@internationalized/date";

import {Button, DateField, DateRangePicker, Description, Label, RangeCalendar} from "@heroui/react";

Validation

Booking period
"use client";

import type {DateValue} from "@internationalized/date";

import {DateField, DateRangePicker, FieldError, Label, RangeCalendar} from "@heroui/react";

Format Options

Control how DateRangePicker values are displayed with props such as granularity, hourCycle, hideTimeZone, and shouldForceLeadingZeros.

"use client";

import type {TimeValue} from "@heroui/react";
import type {DateValue} from "@internationalized/date";

Disabled

Trip dates
This date range picker is disabled.
"use client";

import {DateField, DateRangePicker, Description, Label, RangeCalendar} from "@heroui/react";
import {getLocalTimeZone, today} from "@internationalized/date";

Custom Indicator

DateRangePicker.TriggerIndicator renders the default IconCalendar when no children are provided. Pass children to replace it.

Trip dates
Replace the default calendar icon by passing custom children.
"use client";

import {DateField, DateRangePicker, Description, Label, RangeCalendar} from "@heroui/react";
import {Icon} from "@iconify/react";

Form Example

Trip dates
Select your check-in and check-out dates.
"use client";

import type {DateValue} from "@internationalized/date";

import {

International Calendar

By default, DateRangePicker displays dates using the calendar system for the user's locale. You can override this by wrapping your DateRangePicker with I18nProvider and setting the Unicode calendar locale extension.

The example below shows the Indian calendar system:

Trip dates
"use client";

import {DateField, DateRangePicker, Label, RangeCalendar} from "@heroui/react";
import {getLocalTimeZone, today} from "@internationalized/date";
import {I18nProvider} from "react-aria-components";

Note: The onChange event always returns dates in the same calendar system as the value or defaultValue (Gregorian if no value is provided), regardless of the displayed locale.

For a complete list of supported calendar systems and their identifiers, see:

Custom Render Function

Trip dates
"use client";

import {DateField, DateRangePicker, Label, RangeCalendar} from "@heroui/react";

export function CustomRenderFunction() {

Styling

Passing Tailwind CSS classes

You can style each composition part independently:

import {DateField, DateRangePicker, Label, RangeCalendar} from '@heroui/react';

function CustomDateRangePicker() {
  return (
    <DateRangePicker className="w-[360px] gap-2">
      <Label className="text-sm font-semibold">Trip dates</Label>
      <DateField.Group className="rounded-xl border border-border/60 bg-surface" fullWidth variant="secondary">
        <DateField.Input slot="start">
          {(segment) => <DateField.Segment segment={segment} />}
        </DateField.Input>
        <DateRangePicker.RangeSeparator className="px-2 text-default" />
        <DateField.Input slot="end">
          {(segment) => <DateField.Segment segment={segment} />}
        </DateField.Input>
        <DateField.Suffix>
          <DateRangePicker.Trigger className="w-full">
            <DateRangePicker.TriggerIndicator className="text-default" />
          </DateRangePicker.Trigger>
        </DateField.Suffix>
      </DateField.Group>
      <DateRangePicker.Popover className="rounded-xl p-2">
        <RangeCalendar aria-label="Custom range picker calendar">
          {/* RangeCalendar parts */}
        </RangeCalendar>
      </DateRangePicker.Popover>
    </DateRangePicker>
  );
}

Customizing the component classes

To customize DateRangePicker base classes, use @layer components.

@layer components {
  .date-range-picker {
    @apply inline-flex flex-col gap-1;
  }

  .date-range-picker__trigger {
    @apply inline-flex items-center justify-between;
  }

  .date-range-picker__trigger-indicator {
    @apply text-muted;
  }

  .date-range-picker__range-separator {
    @apply px-2 text-default;
  }

  .date-range-picker__popover {
    @apply min-w-[var(--trigger-width)] p-0;
  }
}

HeroUI follows BEM naming for reusable customization.

CSS Classes

DateRangePicker uses these classes in packages/styles/components/date-range-picker.css:

  • .date-range-picker - Root wrapper.
  • .date-range-picker__trigger - Trigger part that opens the popover.
  • .date-range-picker__trigger-indicator - Default/custom indicator slot.
  • .date-range-picker__range-separator - Separator between start and end date inputs.
  • .date-range-picker__popover - Popover content wrapper.

Interactive States

DateRangePicker supports React Aria data attributes and pseudo states:

  • Open: [data-open="true"] on trigger.
  • Disabled: [data-disabled="true"] or [aria-disabled="true"] on trigger.
  • Focus visible: :focus-visible or [data-focus-visible="true"] on trigger.
  • Hover: :hover or [data-hovered="true"] on trigger.

API Reference

DateRangePicker Props

DateRangePicker inherits all props from React Aria DateRangePicker.

PropTypeDefaultDescription
value{ start: DateValue; end: DateValue } | null-Controlled selected date range value.
defaultValue{ start: DateValue; end: DateValue } | null-Default selected range in uncontrolled mode.
onChange(value: { start: DateValue; end: DateValue } | null) => void-Called when selected range changes.
isOpenboolean-Controlled popover open state.
defaultOpenbooleanfalseInitial popover open state.
onOpenChange(isOpen: boolean) => void-Called when popover open state changes.
isDisabledbooleanfalseDisables range selection and trigger interactions.
isInvalidboolean-Marks the field as invalid for validation state.
minValueDateValue-Minimum selectable date.
maxValueDateValue-Maximum selectable date.
startNamestring-Name used for the start date in HTML form submission.
endNamestring-Name used for the end date in HTML form submission.
childrenReactNode | (values: DateRangePickerRenderProps) => ReactNode-Composed content or render function.
renderDOMRenderFunction<keyof React.JSX.IntrinsicElements, DateRangePickerRenderProps>-Overrides the default DOM element with a custom render function.

Composition Parts

ComponentDescription
DateRangePicker.RootRoot date range picker container and state owner.
DateRangePicker.TriggerTrigger button, usually rendered inside DateField.Suffix.
DateRangePicker.TriggerIndicatorIndicator slot with default calendar icon.
DateRangePicker.RangeSeparatorSeparator part between start and end date inputs.
DateRangePicker.PopoverPopover wrapper for RangeCalendar content.
  • @internationalized/date — date types (CalendarDate, CalendarDateTime, ZonedDateTime) and utilities used by all date components
  • I18nProvider — override locale for a subtree
  • useLocale — read the current locale and layout direction

DatePicker

Composable date picker built on React Aria DatePicker with DateField and Calendar composition

Description

Provides supplementary text for form fields and other components

On this page

ImportUsageAnatomyControlledValidationFormat OptionsDisabledCustom IndicatorForm ExampleInternational CalendarCustom Render FunctionStylingPassing Tailwind CSS classesCustomizing the component classesCSS ClassesInteractive StatesAPI ReferenceDateRangePicker PropsComposition PartsRelated packages