Skip to main content

Custom Components

Use the components prop to extend each rendered HTML element with your own custom components.

Prop NameTypeDescription
componentsCustomComponentsChange the components of the calendar.

You may need to use custom components in advanced applications to:

  • Prevent default events from occurring
  • Add new event listeners, such as touch events
  • Display extra content, such as a calendar entry in the day cell
  • Implement buttons or dropdowns using your own design system components
  • Wrap an element with another element, like adding a tooltip to a day cell

When customizing components, familiarize yourself with the API Reference and the DayPicker Anatomy. Ensure you maintain accessibility.

Custom Components vs Formatters

Custom components allow you to extend DayPicker beyond just using formatters. While formatters modify the content within the calendar, custom components enable you to alter the structure of the HTML elements.

Implementing a Custom Component​

Pass the components to customize to the components prop. See the list of custom components below.

<DayPicker
components={{
Day: (props: DayProps) => <CustomDaycell {...props} />,
MonthGrid: (props: MonthGridProps) => <CustomMonthGrid {...props} />
// etc
}}
/>

List of Custom Components​

NameDescription
CaptionLabelThe caption label of the month grid.
ChevronThe chevron icon used in the navigation buttons and dropdowns.
DayThe day cell in the month grid.
DayButtonThe button containing the day in the day cell.
DropdownThe dropdown element to select years and months.
DropdownNavThe container of the dropdowns.
FooterThe footer element announced by screen readers.
MonthThe container of the MonthGrid.
MonthCaptionThe caption of the month grid.
MonthGridThe grid of days in a month.
MonthsWrapper of the month grids.
MonthsDropdownThe dropdown with the months.
NavThe navigation element with the next and previous buttons.
NextMonthButtonThe next month button element in the navigation.
OptionThe <option> HTML element in the dropdown.
PreviousMonthButtonThe previous month button element in the navigation.
RootThe root element of the calendar.
SelectThe select element in the dropdowns.
WeekThe week rows.
WeekNumberThe cell with the number of the week.
WeekNumberHeaderThe header of the week number column.
WeekdayThe weekday name in the header.
WeekdaysThe row containing the week days.
WeeksThe weeks section in the month grid.
YearsDropdownThe dropdown with the years.

Examples​

Intercepting Click Events​

For example, you can use a custom DayButton to select days with a double-click event.

./MyDatePicker.tsx
import React from "react";

import { DayPicker } from "react-day-picker";

export function MyDatePicker() {
const [selected, setSelected] = React.useState<Date>();
return (
<DayPicker
mode="single"
onSelect={setSelected}
selected={selected}
components={{
DayButton: (props) => {
const { day, modifiers, ...buttonProps } = props;
return (
<button
{...buttonProps}
// Prevent the default click event
onClick={() => setSelected(undefined)}
// Handle the double click event and reset the selection
onDoubleClick={() => setSelected(day.date)}
/>
);
}
}}
footer={selected?.toDateString() || "Double click to select a date"}
/>
);
}
October 2024
SuMoTuWeThFrSa

What are you using custom components for? Let us know.

DayPicker Hook​

In a custom component, import the useDayPicker hook to access the DayPicker context.

import { useDayPicker } from "react-day-picker";
FunctionReturn valueDescription
useDayPickerDayPickerContextReturn the current state of DayPicker and functions to navigate the calendar

DayPicker Context​

The DayPicker context provides the current state of the calendar, including the selected days, modifiers, and navigation state.

NameTypeDescription
classNamesClassNamesThe class names for the UI elements.
componentsCustomComponentsThe components used internally by DayPicker.
formattersFormattersThe formatters used to format the UI elements.
getModifiers(day) => ModifiersReturns the modifiers for the given day.
goToMonth(month) => voidNavigate to the specified month.
isSelected(date) => boolean | undefinedWhether the given date is selected.
labelsLabelsThe labels used in the user interface.
monthsCalendarMonth[]The months displayed in the calendar.
nextMonthDate | undefinedThe next month to display.
previousMonthDate | undefinedThe previous month to display.
selectSelectHandler<T> | undefinedSet a selection.
selectedSelectedValue<T> | undefinedThe selected date(s).
stylesPartial<Styles> | undefinedThe styles for the UI elements.