DateRangePicker uses typed objects from [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) instead of native JavaScript `Date`. Import date utilities from `@cfa/react-core/dates` and components from `@cfa/react-core`. See the [Dates and Times guide](/guides/dates-and-times) for how to create values and convert to and from `Date`.
For an inline calendar without fields, use [RangeCalendar](RangeCalendar.md).
## Import
```jsx
import { DateRangePicker, DateRangeField } from "@cfa/react-core";
import { CalendarDate, CalendarDateTime } from "@cfa/react-core/dates";
```
## Live Editor
```jsx
```
## Guidelines
### When to use
- DateRangePicker is for a start and end date people pick as one value, shown as a span in a calendar.
### Do
- Disable invalid days, such as days before the start date, days past a maximum span, and blackout days. Update disabled days dynamically when constraints depend on the start date.
- Show a clear inline error when the typed range violates a constraint.
### Avoid
- Using DateRangePicker when only one date matters. Use DatePicker.
- Using DateRangePicker when the two dates are unrelated. Use two DatePickers.
- Using DateRangePicker when the unit is time of day. Use TimeInput.
- Using DateRangePicker when the range is one of a few preset choices with no custom picking. Use Select or RadioGroup.
- Using DateRangePicker when the range is really a duration. Use NumberInput and a unit selector.
- Silently snapping a typed range to a valid value.
## Examples
### Basic Usage
The most common way to use DateRangePicker is with the composite component.
```jsx
```
### Composable Usage
For more control and customization, use the individual DateRangeField subcomponents.
```jsx
Event Date Range
Select the start and end dates for your event.
```
### Controlled Usage
Control the date range value from a parent component.
```jsx
function ControlledExample() {
const [dateRange, setDateRange] = React.useState(null);
return (
<>
Selected: {dateRange ? `${dateRange.start} to ${dateRange.end}` : "none"}
);
}
```
### Date Range Constraints
Set minimum and maximum dates to restrict the selectable range.
```jsx
```
### Unavailable Dates
Disable specific dates using the `isDateUnavailable` prop. The example below prevents selection of weekends.
```jsx
isWeekend(date, "en-US")}
/>
```
### Date Highlighting
Highlight specific dates in the calendar using the `isDateHighlighted` prop. This example highlights the 1st and 15th of each month.
```jsx
date.day === 1 || date.day === 15}
/>
```
### Non-Contiguous Ranges
Allow users to select non-contiguous date ranges for more flexible selection.
```jsx
```
### Validation States
The DateRangePicker component supports different validation states.
```jsx
```
### Date and Time Ranges
Use different granularities for date and time range selection.
```jsx
```
### Custom Calendar Display
Customize the calendar display with different first day of week and visible duration.
```jsx
```
### Sizes
Use the `size` prop (`sm`, `md`, or `lg`) to control field height, padding, and segment typography. Default is `md` (40px).
```jsx
```
## Props
### DateRangePicker
| Name | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| compact | `boolean` | - | @deprecated Use \`size="md"\` instead. This prop is a no-op. |
| description | `string` | - | Description for the date range picker |
| errorMessage | `string \ | ((validation: ValidationResult) => string)` | - | Error message to display when isInvalid is true |
| hideOutsideDays | `boolean` | `false` | Hides days that belong to the previous or next month. The cells stay in the grid so week columns remain aligned. |
| isDateHighlighted | `((date: T) => boolean)` | - | - |
| isReadOnly | `boolean` | - | Makes the date range picker read-only when true |
| label | `string` | - | Label for the date range picker |
| size | `"lg" \ | "md" \ | "sm"` | `"md"` | Controls field height, padding, and segment typography. |
| allowsNonContiguousRanges | `boolean` | - | When combined with \`isDateUnavailable\`, determines whether non-contiguous ranges, i.e. ranges containing unavailable dates, may be selected. |
| aria-describedby | `string` | - | Identifies the element (or elements) that describes the object. |
| aria-details | `string` | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| aria-label | `string` | - | Defines a string value that labels the current element. |
| aria-labelledby | `string` | - | Identifies the element (or elements) that labels the current element. |
| autoFocus | `boolean` | - | Whether the element should receive focus on render. |
| children | `ChildrenOrFunction` | - | The children of the component. A function may be provided to alter the children based on component state. |
| className | `ClassNameOrFunction` | `'react-aria-DateRangePicker'` | The CSS \[className]\(https\://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| defaultFocusedValue | `DateValue \ | null` | - | The date that is focused when the calendar first mounts (uncontrolled). |
| defaultOpen | `boolean` | - | Whether the overlay is open by default (uncontrolled). |
| defaultValue | `RangeValue \ | null` | - | The default value (uncontrolled). |
| dir | `string` | - | - |
| endName | `string` | - | The name of the end date input element, used when submitting an HTML form. See \[MDN]\(https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| firstDayOfWeek | `"fri" \ | "mon" \ | "sat" \ | "sun" \ | "thu" \ | "tue" \ | "wed"` | - | The day that starts the week. |
| focusedValue | `DateValue \ | null` | - | Controls the currently focused date within the calendar. |
| form | `string` | - | The \`\