Skip to main content

Customization

Use the customization props to tailor the calendar's appearance.

Prop NameTypeDescription
captionLayout"label"
"dropdown"
"dropdown-months"
"dropdown-years"
Choose the layout of the month caption. Default is label.
navLayout"around" | "after"Adjust the positioning of the navigation buttons.
fixedWeeksbooleanDisplay 6 weeks per month.
footerReactNode | stringAdd a footer to the calendar, acting as a live region.
hideWeekdaysbooleanHide the row displaying the weekday names.
numberOfMonthsnumberThe number of displayed months. Default is 1.
showOutsideDaysbooleanDisplay the days falling into other months.
showWeekNumberbooleanDisplay the column with the week numbers.

Caption Layouts

Use the captionLayout prop to customize the layout of the month caption.

<DayPicker captionLayout="label" /> // Default value: shows the month and year.
Caption LayoutDescription
"label"Displays the month and year as a label. Default value.
"dropdown"Displays a dropdown with both months and years.
"dropdown-months"Displays a dropdown with the months only.
"dropdown-years"Displays a dropdown with the years only.

Caption Dropdown

To enable a navigation dropdown, set captionLayout="dropdown". Use the startMonth and endMonth properties to define the start and end dates for the calendar navigation.

<DayPicker
captionLayout="dropdown"
defaultMonth={new Date(2024, 6)}
startMonth={new Date(2024, 6)}
endMonth={new Date(2025, 9)}
/>
Default Range

Without specifying the startMonth and endMonth properties, the dropdown will display the last 100 years.

Use the navLayout prop to adjust the positioning of the navigation buttons.

Navigation LayoutDescription
"around"Buttons are displayed on either side of the caption.
"after"Buttons are displayed after the caption, ensuring the tab order matches the visual order.
undefinedButtons are displayed after the caption, but the tab order may not match the visual order.
<DayPicker navLayout="around" />
<DayPicker navLayout="after" />

See Navigation for additional ways to customize the calendar’s navigation.

Tab Order vs. Visual Order

If not set, the navigation buttons default to being displayed after the caption. However, the tab order may not align with the visual order when setting "dropdown" as caption layout. To ensure the component remains accessible, set navLayout to "after" or to "around" instead of leaving it undefined.

In a future version, the default behavior will be changed to "after".

Outside Days

By default, DayPicker hides the days falling into other months. Use showOutsideDays to display them.

<DayPicker showOutsideDays />

Fixed Weeks

In a year, months can have between 4 and 6 weeks. Use the fixedWeeks prop to always display 6 weeks per month. This will prevent the grid from changing its height while navigating the calendar.

<DayPicker fixedWeeks showWeekNumber />

Multiple Months

To display multiple months in the calendar, use the numberOfMonths prop.

Prop NameTypeDescription
numberOfMonthsnumberThe number of displayed months. Default is 1.
pagedNavigationbooleanPaginate the navigation.
reverseMonthsbooleanRender multiple months in reversed order.
<DayPicker numberOfMonths={2} />

Paged Navigation

With pagedNavigation, the navigation jumps by the specified number of months at a time.

<DayPicker numberOfMonths={2} pagedNavigation />

Week Numbers

To display the column with week numbers, use the showWeekNumber prop.

Prop NameTypeDescription
showWeekNumberbooleanDisplay the week numbers.
<DayPicker showWeekNumber />

Handling Week Numbers Click

To handle clicks on the week numbers, you can set the WeekNumber custom component:

<DayPicker
showWeekNumber
components={{
WeekNumber: (props) => (
<button onClick={() => alert(`Week ${props.weekNumber}`)}>
{props.weekNumber}
</button>
)
}}
/>

Selecting the Whole Week

In selection mode, you can create a custom selection that selects the entire week when a day is clicked.

Use the footer prop to display a footer below the calendar. The footer acts as a live region to announce changes to screen readers. For more information on making the calendar accessible, see the Accessibility guide.

export function Footer() {
const [selected, setSelected] = React.useState<Date>();
return (
<DayPicker
mode="single"
selected={selected}
onSelect={setSelected}
footer={
selected
? `You picked ${selected.toLocaleDateString()}.`
: "Please pick a date."
}
/>
);
}

Custom Components

In DayPicker, you can replace the components used internally to render the calendar. For more information, see the Custom Components guide.

Prop NameTypeDescription
componentsCustomComponentsChange the internal components used to render the calendar.
classNamesClassNamesUse custom class names instead of the default ones.