---
title: Date Range Picker
description: DateRangePicker combine a DateField and a RangeCalendar overlay to allow users to enter or select a date and time range.
thumbnail:
  image: /previews/components/core/date-range-picker.jpeg
  video: /previews/components/core/date-range-picker.mp4
---

<ComponentPreview
  name="core/date-range-picker-default"
  preview={`<DateRangePicker />`}
/>

## Installation

<Tabs items={["CLI", "Manual"]}>
  <Tab value="CLI">
  
  ```package-install
npx dotui-cli@latest add date-range-picker
```

  </Tab>
  <Tab value="manual">
  
    <Steps>
      <Step>Install the following dependencies:</Step>

    ```package-install
    react-aria-components
    ```

      <Step>Copy and paste the following code into your project.</Step>
      <ComponentSource name="core/date-range-picker" />
      <Step>Update the import paths to match your project setup.</Step>
    </Steps>

  </Tab>
</Tabs>

## Usage

Use a `DateRangePicker` to allow users to enter and edit time values.

## Options

### Label

A visual label can be provided for the `DateRangePicker` using the label prop or a hidden label using `aria-label` prop.<br/>

<ComponentPreview
  name="core/date-range-picker-label"
  preview={`<DateRangePicker label="Trip" />
<DateRangePicker aria-label="Trip" />`}
/>

### Size

Use the `size` prop to control the size of the `DateRangePicker`.<br/>
The default variant is `"md"`.

<ComponentPreview
  name="core/date-range-picker-sizes"
  preview={`<DateRangePicker label="small" size="sm" />
<DateRangePicker label="medium" size="md" />
<DateRangePicker label="large" size="lg" />`}
/>

### Prefix

To add additional context for the `DateRangePicker`, use the `prefix` prop.

<ComponentPreview
  name="core/date-range-picker-prefix"
  preview={`<DateRangePicker prefix={<PlaneIcon />} />`}
/>

### Description

A description can be supplied to `DateRangePicker` via the `description` prop. The description is always visible unless the `isInvalid` prop is `true` and an error message is provided.

<ComponentPreview
  name="core/date-range-picker-description"
  preview={`<DateRangePicker label="Trip" description="Please select a date range." />`}
/>

### Contextual help

A `ContextualHelp` element may be placed next to the label to provide additional information or help about a `DateRangePicker`.

<ComponentPreview
  name="core/date-range-picker-contextual-help"
  preview={`<DateRangePicker label="Appointment" contextualHelp={<ContextualHelp />} />`}
/>

### Error message

An `errorMessage` can be supplied to a `DateRangePicker`, which will be displayed when the `isInvalid` prop is set to `true`.

<ComponentPreview
  name="core/date-range-picker-error-message"
  preview={`<DateRangePicker
    label="Trip dates"
    isInvalid
    errorMessage="Trip dates can't be scheduled in the past."
  />`}
/>

### Time zones

`DateRangePicker` is time zone aware when a ZonedDateTime object is provided as the value.

<ComponentPreview
  name="core/date-range-picker-time-zones"
  preview={`<DateRangePicker
    defaultValue={{
      start: parseAbsoluteToLocal("2021-04-07T18:45:22Z"),
      end: parseAbsoluteToLocal("2021-04-08T20:00:00Z"),
    }}
  />`}
/>

### Granularity

The `granularity` prop allows you to control the smallest unit that is displayed by DateRangePicker.

<ComponentPreview
  name="core/date-range-picker-granularity"
  preview={`<DateRangePicker label="Hour" granularity="hour" defaultValue={dates} />
<DateRangePicker label="Minute" granularity="minute" defaultValue={dates} />
<DateRangePicker label="Second" granularity="second" defaultValue={dates} />`}
/>

### Placeholder value

Use the `placeholderValue` prop to control the default values of each segment. The default value is midnight.

<ComponentPreview
  name="core/date-range-picker-placeholder"
  preview={`<DateRangePicker label="Meeting date" placeholderValue={new CalendarDate(1980, 1, 1)} />`}
/>

### Hide time zone

Use the `hideTimeZone` prop to hide the time zone abbreviation.

<ComponentPreview
  name="core/date-range-picker-hide-time-zone"
  preview={`<DateRangePicker
    label="Appointment time"
    granularity="minute"
    defaultValue={{
      start: parseAbsoluteToLocal("2021-04-07T18:45:22Z"),
      end: parseAbsoluteToLocal("2021-04-08T20:00:00Z"),
    }}
    hideTimeZone
  />`}
/>

### Hour cycle

Use the `hourCycle` prop to control the hour cycle of the `DateRangePicker`.

<ComponentPreview
  name="core/date-range-picker-hour-cycle"
  preview={`<DateRangePicker granularity="minute" hourCycle={24} />`}
/>

### Loading

Use the `isLoading` prop to control the loading state of the `DateRangePicker`.

<ComponentPreview
  name="core/date-range-picker-loading"
  preview={`<DateRangePicker isLoading />`}
/>

### Disabled

Use the `isDisabled` prop to disable the `DateRangePicker`.

<ComponentPreview
  name="core/date-range-picker-disabled"
  preview={`<DateRangePicker label="Trip dates" isDisabled />`}
/>

### ReadOnly

The `isReadOnly` boolean prop makes the `DateRangePicker`'s text content immutable. Unlike `isDisabled`, the `DateRangePicker` remains focusable and the contents can still be copied.

<ComponentPreview
  name="core/date-range-picker-read-only"
  preview={`<DateRangePicker
    label="Event date"
    value={{
      start: parseAbsoluteToLocal("2021-04-07T18:45:22Z"),
      end: parseAbsoluteToLocal("2021-04-08T20:00:00Z"),
    }}
    isReadOnly
  />`}
/>

### Required

Use the `isRequired` prop to mark the `DateRangePicker` as required.
Use the `necessityIndicator` prop to control the visual style of the required state.

<ComponentPreview
  name="core/date-range-picker-required"
  preview={`<DateRangePicker label="Event date" isRequired />
  <DateRangePicker label="Event date" isRequired necessityIndicator="icon" />
  <DateRangePicker label="Event date" isRequired necessityIndicator="label" />
  <DateRangePicker label="Event date" necessityIndicator="label" />`}
/>

## Uncontrolled

An initial, uncontrolled value can be provided to the `DateRangePicker` using the `defaultValue` prop.

<ComponentPreview
  name="core/date-range-picker-uncontrolled"
  preview={`<DateRangePicker
  label="Controlled"
  defaultValue={{
    start: parseDate("2020-02-03"),
    end: parseDate("2020-02-08"),
  }}
/>`}
/>

## Controlled

Use the `value` and `onChange` props to control the value of the input.

<ComponentPreview
  name="core/date-range-picker-controlled"
  preview={`const [value, setValue] = React.useState({
  start: parseDate("2024-02-03"),
  end: parseDate("2024-02-08"),
});
return <DateRangePicker label="Controlled" value={value} onChange={setValue} />`}
/>

## Composition

If you need to customize things further, you can drop down to the composition level.

<ComponentPreview
  name="core/date-range-picker-composition"
  preview={`<DatePickerRoot>
  <Label>Meeting date</Label>
  <InputRoot suffix={<Button><CalendarIcon /></Button>}>
    <DateInput slot="start">{(segment) => <DateSegment segment={segment} />}</DateInput>
    <span>–</span>
    <DateInput slot="end">{(segment) => <DateSegment segment={segment} />}</DateInput>
  </InputRoot>
  <Description>Please select a date.</Description>
  <FieldError />
  <Overlay type="popover" mobileType="drawer">
    <DialogContent>
      <RangeCalendar />
    </DialogContent>
  </Overlay>
</DatePickerRoot>`}
/>

## API Reference

| Prop                        | Type                                                                                                    | Default     | Description                                                                                                                                                                                                                           |
| --------------------------- | ------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pageBehavior`              | `'single' \| 'visible'`                                                                                 | `'visible'` | Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.                                                                                   |
| `minValue`                  | `DateValue`                                                                                             | -           | The minimum allowed date that a user may select.                                                                                                                                                                                      |
| `maxValue`                  | `DateValue`                                                                                             | -           | The maximum allowed date that a user may select.                                                                                                                                                                                      |
| `isDateUnavailable`         | `(date: DateValue) => boolean`                                                                          | -           | Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.                                                                                                                              |
| `placeholderValue`          | `DateValue`                                                                                             | -           | A placeholder date that influences the format of the placeholder shown when no value is selected. Defaults to 12:00 AM or 00:00 depending on the hour cycle.                                                                          |
| `hourCycle`                 | `12 \| 24`                                                                                              | -           | Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale.                                                                                                                             |
| `granularity`               | `'hour' \| 'minute' \| 'second'`                                                                        | -           | Determines the smallest unit that is displayed in the date picker. By default, this is "day" for dates, and "minute" for times.                                                                                                       |
| `hideTimeZone`              | `boolean`                                                                                               | `false`     | Whether to hide the time zone abbreviation.                                                                                                                                                                                           |
| `shouldForceLeadingZeros`   | `boolean`                                                                                               | -           | Whether to always show leading zeros in the hour field. By default, this is determined by the user's locale.                                                                                                                          |
| `isDisabled`                | `boolean`                                                                                               | -           | Whether the input is disabled.                                                                                                                                                                                                        |
| `isReadOnly`                | `boolean`                                                                                               | -           | Whether the input can be selected but not changed by the user.                                                                                                                                                                        |
| `isRequired`                | `boolean`                                                                                               | -           | Whether user input is required on the input before form submission.                                                                                                                                                                   |
| `isInvalid`                 | `boolean`                                                                                               | -           | Whether the input value is invalid.                                                                                                                                                                                                   |
| `autoFocus`                 | `boolean`                                                                                               | -           | Whether the element should receive focus on render.                                                                                                                                                                                   |
| `isOpen`                    | `boolean`                                                                                               | -           | Whether the overlay is open by default (controlled).                                                                                                                                                                                  |
| `defaultOpen`               | `boolean`                                                                                               | -           | Whether the overlay is open by default (uncontrolled).                                                                                                                                                                                |
| `allowsNonContiguousRanges` | `boolean`                                                                                               | -           | When combined with isDateUnavailable, determines whether non-contiguous ranges, i.e. ranges containing unavailable dates, may be selected.                                                                                            |
| `startName`                 | `string`                                                                                                | -           | The name of the start date input element, used when submitting an HTML form.                                                                                                                                                          |
| `endName`                   | `string`                                                                                                | -           | The name of the end date input element, used when submitting an HTML form.                                                                                                                                                            |
| `validate`                  | `(value: RangeValue<MappedDateValue<DateValue>>) => ValidationError  \| true  \| null  \| undefined`    | -           | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead. |
| `value`                     | `RangeValue<DateValue> \| null`                                                                         | -           | The current value (controlled).                                                                                                                                                                                                       |
| `defaultValue`              | `RangeValue<DateValue> \| null`                                                                         | -           | The default value (uncontrolled).                                                                                                                                                                                                     |
| `shouldCloseOnSelect`       | `boolean \| () => boolean`                                                                              | `true`      | Determines whether the date picker popover should close automatically when a date is selected.                                                                                                                                        |
| `validationBehavior`        | `'native' \| 'aria'`                                                                                    | `'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.                                                                        |
| `children`                  | `ReactNode \| (values: DatePickerRenderProps & {defaultChildren: ReactNode \| undefined}) => ReactNode` | -           | The children of the component. A function may be provided to alter the children based on component state.                                                                                                                             |
| `className`                 | `string`                                                                                                | -           | The CSS className for the element.                                                                                                                                                                                                    |
| `style`                     | `CSSProperties \| (values: DatePickerRenderProps & {defaultStyle: CSSProperties}) => CSSProperties`     | -           | The inline style for the element. A function may be provided to compute the style based on component state.                                                                                                                           |

| Event           | Type                                          | Description                                                     |
| --------------- | --------------------------------------------- | --------------------------------------------------------------- |
| `onFocus`       | `(e: FocusEvent<Target>) => void`             | Handler that is called when the element receives focus.         |
| `onBlur`        | `(e: FocusEvent<Target>) => 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.                  |
| `onOpenChange`  | `(isOpen: boolean) => void`                   | Handler that is called when the overlay's open state changes.   |
| `onChange`      | `(value: MappedDateValue<DateValue>) => void` | Handler that is called when the value changes.                  |

| Data attribute         | Description                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------- |
| `[data-focus-within]`  | Whether an element within the date picker is focused, either via a mouse or keyboard. |
| `[data-focus-visible]` | Whether an element within the date picker is keyboard focused.                        |
| `[data-disabled]`      | Whether the date picker is disabled.                                                  |
| `[data-invalid]`       | Whether the date picker is invalid.                                                   |
| `[data-open]`          | Whether the date picker is open.                                                      |
