A month grid to pick a day with the mouse or the keyboard. DatePicker uses it, and you can use it alone when the calendar should always be visible.
In Next.js 16 with cacheComponents on, wrap a Calendar that is always visible in <Suspense>. It reads today's date while it renders, and Next does not prerender that. A DatePicker does not need it, because its calendar opens on a click.
Pass the selected day with value and listen to onChange.
Days outside the range are disabled and the keyboard does not go there.
locale sets the names of the month and of the weekdays, and weekStartsOn the first column (0 is Sunday).
With mode set to multiple each click adds or removes a day, and value is an array. Use maxSelected to limit how many.
With mode set to range the first click sets the start and the second the end. value is [start, end].
shouldDisableDate receives each day and returns true to block it, like weekends or holidays.
showOutsideDays fills the grid with days of the neighbor months, and showWeekNumbers adds the ISO week of each row.
numberOfMonths shows the months side by side. A range can cross from one to the next, and the days of the neighbor months are hidden.
| Attribute | Description | Type | Accepted values | Default |
|---|---|---|---|---|
| value | selected day, days or range, to control the component | Date / null, Date[] or [Date, Date] | - | - |
| onChange | called with what the user picked, in the shape of value | (value) => void | - | - |
| min | first day that can be picked | Date | - | - |
| max | last day that can be picked | Date | - | - |
| locale | language of the month and weekday names | string | any Intl locale | en-US |
| weekStartsOn | first day of the week, 0 is Sunday | number | 0 to 6 | 0 |
| mode | how many days can be picked | string | 'single', 'multiple', 'range' | single |
| maxSelected | most days in multiple mode | number | - | - |
| shouldDisableDate | disable the days where it returns true | (date: Date) => boolean | - | - |
| showOutsideDays | show days of the neighbor months | boolean | - | false |
| numberOfMonths | months shown side by side; hides the neighbor days if more than one | number | - | 1 |
| showWeekNumbers | show the ISO week of each row | boolean | - | false |
| month | visible month, to control it | Date | - | - |
| defaultMonth | visible month at the start | Date | - | the selected day |
| onMonthChange | called with the first day of the new month | (month: Date) => void | - | - |
| weekLabel | name of the week number column | string | - | Week |
| autoFocus | move the focus to the day when it is shown | boolean | - | false |
| previousLabel | name of the previous month button | string | - | Previous month |
| nextLabel | name of the next month button | string | - | Next month |
| ... | native props | HTMLAttributes | 'id', 'className', ... | - |
The ref points at the root element.
The days are a grid named by the month, with a single tab stop on the focused day. The selected day has aria-selected and today has aria-current="date".
| Key | Action |
|---|---|
| Arrow keys | Move by one day, or one week |
| Home and End | Go to the first and to the last day of the week |
| Page Up and Page Down | Go to the previous and to the next month |
| Shift and Page Up or Down | Go to the previous and to the next year |
| Enter and Space | Pick the day |