# DatePicker
**Category**: react
**URL**: https://www.heroui.com/docs/react/migration/date-picker
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/migration/(components)/date-picker.mdx
> Migration guide for DatePicker from HeroUI v2 to v3
***
Refer to the [v3 DatePicker documentation](/docs/react/components/date-picker) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.
## Structure Changes
In v2, `DatePicker` was a single self-contained component with props for label, description, calendar, and time input:
```tsx
import { DatePicker } from "@heroui/react";
export default function App() {
return (
);
}
```
In v3, DatePicker uses a composition-first API where you compose `DateField` and `Calendar` explicitly:
```tsx
import { DatePicker, DateField, Calendar, Label } from "@heroui/react";
export default function App() {
return (
{(segment) => }
{(day) => {day}}
{(date) => }
);
}
```
## Key Changes
### 1. Component Structure
**v2:** Single `DatePicker` component with all parts (input, calendar, label, popover) handled internally via props
**v3:** Composition-based API with `DatePicker`, `DateField`, `Calendar`, and `Label` composed together. Each part is a separate component.
### 2. Composition Parts
| v3 Component | Description |
|-----------|-------------|
| `DatePicker` | Root container and state owner |
| `DatePicker.Trigger` | Button that opens the calendar popover |
| `DatePicker.TriggerIndicator` | Calendar icon (default) or custom indicator |
| `DatePicker.Popover` | Popover wrapper for the calendar |
| `DateField.Group` | Input group wrapper |
| `DateField.Input` | Segmented date input |
| `DateField.Segment` | Individual date segment (month, day, year) |
| `DateField.Suffix` | Suffix slot for the trigger button |
| `Calendar` | Full calendar component (see [Calendar migration](/docs/react/migration/calendar)) |
| `Label` | External label component |
### 3. Prop Changes
| v2 Prop | v3 Equivalent | Notes |
|---------|---------------|-------|
| `value` | `value` | Same |
| `defaultValue` | `defaultValue` | Same |
| `onChange` | `onChange` | Same |
| `minValue` | `minValue` | Same |
| `maxValue` | `maxValue` | Same |
| `isDateUnavailable` | `isDateUnavailable` | Same |
| `isDisabled` | `isDisabled` | Same |
| `isReadOnly` | `isReadOnly` | Same |
| `isRequired` | `isRequired` | Same |
| `isInvalid` | `isInvalid` | Same |
| `granularity` | `granularity` | Same |
| `hourCycle` | `hourCycle` | Same |
| `hideTimeZone` | `hideTimeZone` | Same |
| `shouldForceLeadingZeros` | `shouldForceLeadingZeros` | Same |
| `pageBehavior` | - | Set on `Calendar` directly |
| `label` | - | Use `Label` component |
| `description` | - | Use `Description` component |
| `errorMessage` | - | Use `FieldError` component |
| `variant` | - | Use `DateField.Group` `variant` prop or Tailwind CSS |
| `color` | - | Removed (use Tailwind CSS) |
| `size` | - | Removed (use Tailwind CSS) |
| `radius` | - | Removed (use Tailwind CSS) |
| `labelPlacement` | - | Control layout with Tailwind CSS |
| `startContent` | - | Compose inside `DateField.Group` |
| `endContent` | - | Compose inside `DateField.Group` |
| `selectorIcon` | - | Pass children to `DatePicker.TriggerIndicator` |
| `visibleMonths` | - | Use `Calendar` `visibleDuration` prop |
| `showMonthAndYearPickers` | - | Use `Calendar.YearPickerTrigger` and `Calendar.YearPickerGrid` |
| `calendarProps` | - | Pass props directly to `Calendar` |
| `popoverProps` | - | Pass props directly to `DatePicker.Popover` |
| `selectorButtonProps` | - | Pass props directly to `DatePicker.Trigger` |
| `timeInputProps` | - | Compose time input separately |
| `CalendarBottomContent` | - | Place content inside `DatePicker.Popover` after `Calendar` |
| `validate` | - | Handle validation externally |
| `placeholderValue` | `placeholderValue` | Same |
| `autoFocus` | `autoFocus` | Same |
| `disableAnimation` | - | Removed |
| `classNames` | - | Use `className` on individual components |
## Migration Examples
### Basic DatePicker
```tsx
import { DatePicker } from "@heroui/react";
```
```tsx
import { DatePicker, DateField, Calendar, Label } from "@heroui/react";
{(segment) => }
{(day) => {day}}
{(date) => }
```
### Controlled State
```tsx
import { useState } from "react";
import { DatePicker } from "@heroui/react";
import { parseDate } from "@internationalized/date";
const [value, setValue] = useState(parseDate("2024-03-07"));
```
```tsx
import { useState } from "react";
import { DatePicker, DateField, Calendar, Label } from "@heroui/react";
import { parseDate } from "@internationalized/date";
const [value, setValue] = useState(parseDate("2024-03-07"));
{(segment) => }
{(day) => {day}}
{(date) => }
```
### With Description and Error Message
```tsx
```
```tsx
import { DatePicker, DateField, Calendar, Label, Description, FieldError } from "@heroui/react";
{(segment) => }
Choose a future date
Date must be in the future
{/* Calendar compound components */}
```
### Custom Selector Icon
```tsx
import { Icon } from "@iconify/react";
}
/>
```
```tsx
import { Icon } from "@iconify/react";
{(segment) => }
{/* Calendar compound components */}
```
### With Month/Year Pickers and Calendar Bottom Content
```tsx
setValue(today(getLocalTimeZone()))}>Today
}
/>
```
```tsx
{(segment) => }
{(day) => {day}}
{(date) => }
{(year) => }
```
## Styling Changes
### v2: `classNames` Prop
```tsx
```
### v3: Direct `className` Props
```tsx
{(segment) => }
{/* Calendar compound components */}
```
## Component Anatomy
The v3 DatePicker follows this structure:
```
DatePicker (Root)
├── Label
├── DateField.Group
│ ├── DateField.Input
│ │ └── DateField.Segment (render prop per segment)
│ └── DateField.Suffix
│ └── DatePicker.Trigger
│ └── DatePicker.TriggerIndicator
├── Description (optional)
├── FieldError (optional)
└── DatePicker.Popover
├── Calendar (see Calendar migration guide)
└── [Custom bottom content]
```
## Summary
1. **Component Structure**: Single component → composition of `DatePicker`, `DateField`, `Calendar`, and `Label`
2. **Label**: `label` prop → `Label` component
3. **Description/Error**: Props → `Description` and `FieldError` components
4. **Calendar**: Built-in → compose `Calendar` with its own compound components inside `DatePicker.Popover`
5. **Selector Icon**: `selectorIcon` prop → pass children to `DatePicker.TriggerIndicator`
6. **Year Picker**: `showMonthAndYearPickers` prop → use `Calendar.YearPickerTrigger` and `Calendar.YearPickerGrid`
7. **Calendar Bottom Content**: `CalendarBottomContent` prop → place content inside `DatePicker.Popover` after `Calendar`
8. **Styling Props Removed**: `variant`, `color`, `size`, `radius` → use Tailwind CSS or `DateField.Group` variant
9. **ClassNames Removed**: Use `className` on individual compound components
10. **Multiple Months**: `visibleMonths` prop → use `Calendar` `visibleDuration` prop