DateRangePicker

Import

tsx

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

Usage

Anatomy

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

tsx

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

export default () => (
  <DateRangePicker>
    <Label />
    <DateField.Group>
      <DateField.InputContainer>
        <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.InputContainer>
      <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

Validation

Format Options

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

Disabled

Custom Indicator

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

Form Example

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:

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

Styling

Passing Tailwind CSS classes

You can style each composition part independently:

tsx

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.InputContainer>
          <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.InputContainer>
        <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>
      </DateRangePicker.Popover>
    </DateRangePicker>
  );
}

Customizing the component classes

To customize DateRangePicker base classes, use @layer components.

css

@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