DatePicker 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`.
## Import
```jsx
import { DatePicker, DateField } from "@cfa/react-core";
import { CalendarDate, CalendarDateTime } from "@cfa/react-core/dates";
```
## Live Editor
```jsx
```
## Guidelines
### When to use
- DatePicker is for a single date, when calendar context improves accuracy or people may not know the exact date.
### Do
- Prefer the typeable field when people already know the date. The calendar popover supplements entry.
- Pair with TimeInput when time-of-day precision is required.
- Disable or constrain dates that fall outside allowed ranges or business rules, including minimums, maximums, and specific blocked dates.
- Show a clear inline error when the typed date violates a constraint.
- Validate when people leave the field or submit the form, not on every keystroke.
### Avoid
- Using DatePicker for date ranges. Use DateRangePicker.
- Using DatePicker for time of day. Use TimeInput.
- Using DatePicker when the choice is one of a few fixed dates. Use Select or RadioGroup.
- Relying on the calendar grid alone.
- Silently snapping a typed date to a valid value.
## Examples
### Basic Usage
The most common way to use DatePicker is with the composite component.
```jsx
```
### Composable Usage
For more control, use the individual subcomponents.
```jsx
Date of BirthThe date you were born.
```
### Controlled Usage
Control the date value from a parent component.
```jsx
function ControlledExample() {
const [date, setDate] = React.useState(null);
return (
<>
Selected: {date ? date.toString() : "none"}
);
}
```
### Date Ranges
Set minimum and maximum dates to restrict selection.
```jsx
```
### Disabled Dates
Disable specific dates using the `isDateUnavailable` prop. The example below disables the 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}
/>
```
### Validation States
The DatePicker component supports different validation states.
```jsx
```
### Date and Time
Use different granularities for date and time selection.
```jsx
```
### Calendar Customizations
Customize the calendar display by changing the first day of week and the number of visible months.
```jsx
```
### Sizes
Use the `size` prop (`sm`, `md`, or `lg`) to control field height, padding, and segment typography. Default is `md` (40px).
```jsx
```
## Props
### DatePicker
| Name | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| compact | `boolean` | - | @deprecated Use \`size="md"\` instead. This prop is a no-op. |
| description | `string` | - | - |
| errorMessage | `string \ | ((validation: ValidationResult) => string)` | - | - |
| 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)` | - | - |
| isInvalid | `boolean` | - | Whether the input value is invalid. |
| isReadOnly | `boolean` | - | Whether the input can be selected but not changed by the user. |
| label | `string` | - | - |
| size | `DateFieldSize` | `"md"` | Controls field height, padding, and segment typography. |
| style | `CSSProperties` | - | The inline \[style]\(https\://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| 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. |
| autoComplete | `string` | - | Describes the type of autocomplete functionality the input should provide if any. See \[MDN]\(https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete). |
| 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-DatePicker'` | 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 | `DateValue \ | null` | - | The default value (uncontrolled). |
| dir | `string` | - | - |
| 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 \`\