docs: enhance custom components and custom selections guides (#2876)

* docs: enhance custom components guide

* docs: flesh out date time picker guide

* docs: expand custom selections guide with runnable examples

* Lint files

Signed-off-by: gpbl <[email protected]>

* docs: fix custom selection examples without default mode

---------

Signed-off-by: gpbl <[email protected]>

Author: gpbl

examples/CustomMonthSelection.tsx

@@ -0,0 +1,35 @@
+import { endOfMonth, startOfMonth } from "date-fns";
+import React, { useState } from "react";
+
+import { type DateRange, DayPicker } from "react-day-picker";
+
+/** Toggle selection of an entire month. */
+export function CustomMonthSelection() {
+  const [monthRange, setMonthRange] = useState<DateRange | undefined>();
+
+  const toMonthRange = (day: Date): DateRange => ({
+    from: startOfMonth(day),
+    to: endOfMonth(day),
+  });
+
+  const isInRange = (day: Date) =>
+    monthRange?.from && monthRange?.to
+      ? day >= monthRange.from && day <= monthRange.to
+      : false;
+
+  return (
+    <DayPicker
+      showOutsideDays
+      modifiers={{
+        selected: monthRange,
+        range_start: monthRange?.from,
+        range_end: monthRange?.to,
+        range_middle: monthRange,
+      }}
+      onDayClick={(day, modifiers) => {
+        if (modifiers.disabled || modifiers.hidden) return;
+        setMonthRange(isInRange(day) ? undefined : toMonthRange(day));
+      }}
+    />
+  );
+}

examples/CustomRollingWindow.tsx

@@ -0,0 +1,37 @@
+import { addDays } from "date-fns";
+import React, { useState } from "react";
+
+import { type DateRange, DayPicker } from "react-day-picker";
+
+/** Select a fixed-length range starting from the clicked day. */
+export function CustomRollingWindow() {
+  const [range, setRange] = useState<DateRange | undefined>();
+  const windowLength = 7;
+
+  const applyRange = (start: Date): DateRange => ({
+    from: start,
+    to: addDays(start, windowLength - 1),
+  });
+
+  return (
+    <DayPicker
+      modifiers={{
+        selected: range,
+        range_start: range?.from,
+        range_end: range?.to,
+        range_middle: range,
+      }}
+      onDayClick={(day, modifiers) => {
+        if (modifiers.disabled || modifiers.hidden) return;
+        setRange(modifiers.selected ? undefined : applyRange(day));
+      }}
+      onDayKeyDown={(day, modifiers, e) => {
+        if (e.key === " " || e.key === "Enter") {
+          e.preventDefault();
+          if (modifiers.disabled || modifiers.hidden) return;
+          setRange(modifiers.selected ? undefined : applyRange(day));
+        }
+      }}
+    />
+  );
+}

examples/InputTime.tsx

@@ -1,18 +1,27 @@
-import { setHours, setMinutes } from "date-fns";
-import React, { type ChangeEventHandler, useState } from "react";
+import { format, setHours, setMinutes } from "date-fns";
+import React, { type ChangeEventHandler, useEffect, useState } from "react";
 import { DayPicker } from "react-day-picker";
 
 export function InputTime() {
   const [selected, setSelected] = useState<Date>();
   const [timeValue, setTimeValue] = useState<string>("00:00");
 
+  // Keep the time input in sync when the selected date changes elsewhere.
+  useEffect(() => {
+    if (selected) {
+      setTimeValue(format(selected, "HH:mm"));
+    }
+  }, [selected]);
+
   const handleTimeChange: ChangeEventHandler<HTMLInputElement> = (e) => {
     const time = e.target.value;
     if (!selected) {
+      // Defer composing a full Date until a day is picked.
       setTimeValue(time);
       return;
     }
     const [hours, minutes] = time.split(":").map((str) => parseInt(str, 10));
+    // Compose a new Date using the current day plus the chosen time.
     const newSelectedDate = setHours(setMinutes(selected, minutes), hours);
     setSelected(newSelectedDate);
     setTimeValue(time);
@@ -26,6 +35,7 @@ export function InputTime() {
     const [hours, minutes] = timeValue
       .split(":")
       .map((str) => parseInt(str, 10));
+    // Apply the time value to the picked day.
     const newDate = new Date(
       date.getFullYear(),
       date.getMonth(),

examples/index.ts

@@ -15,7 +15,9 @@ export * from "./CssVariables";
 export * from "./CustomCaption";
 export * from "./CustomDayButton";
 export * from "./CustomDropdown";
+export * from "./CustomMonthSelection";
 export * from "./CustomMultiple";
+export * from "./CustomRollingWindow";
 export * from "./CustomSingle";
 export * from "./CustomWeek";
 export * from "./DefaultMonth";

website/docs/guides/custom-components.mdx

@@ -18,6 +18,12 @@ You may need to use custom components in advanced applications to:
 - Implement buttons or dropdowns using your own design system components.
 - Wrap an element with another element, like adding a tooltip to a day cell.
 
+## Keep accessibility and behavior intact
+
+- Always forward the props you receive (including `aria-*`, `tabIndex`, `ref`, and event handlers) to preserve keyboard navigation and screen reader support.
+- Reuse `classNames` and `labels` from `useDayPicker` when rendering built-in elements so modifiers and ARIA text remain correct.
+- Prefer composing around the default components instead of rebuilding behavior like focus management in `DayButton`.
+
 When customizing components, familiarize yourself with the [API Reference](../api#components) and the [DayPicker Anatomy](../docs/anatomy.mdx). Ensure you maintain [accessibility](../guides/accessibility.mdx).
 
 :::note Custom Components vs Formatters
@@ -42,6 +48,18 @@ Custom components allow you to extend DayPicker beyond just using [formatters](.
 />
 ```
 
+### Component props cheat sheet
+
+| Component   | Props type                                        | Notes                                                 |
+| ----------- | ------------------------------------------------- | ----------------------------------------------------- |
+| `Day`       | [`DayProps`](../api/functions/Day.md)             | Receives `day` (with `date`) and `modifiers`.         |
+| `DayButton` | [`DayButtonProps`](../api/functions/DayButton.md) | Handles focus; keep forwarding `ref`/`aria-*`.        |
+| `Nav`       | [`NavProps`](../api/functions/Nav.md)             | Use provided `onPreviousClick`/`onNextClick`.         |
+| `Dropdown`  | [`DropdownProps`](../api/functions/Dropdown.md)   | Forward `aria-label` and call `onChange` with target. |
+| `Root`      | [`RootProps`](../api/functions/Root.md)           | Forward `rootRef` when `animate` is enabled.          |
+
+The `components` prop accepts a **partial** map—pass only the entries you want to override. The legacy `Button` entry is deprecated; prefer `NextMonthButton` and `PreviousMonthButton`.
+
 ## List of Custom Components
 
 | Name                                                             | Description                                                    |
@@ -71,6 +89,7 @@ Custom components allow you to extend DayPicker beyond just using [formatters](.
 | [`Weekdays`](../api/functions/Weekdays.md)                       | The row containing the week days.                              |
 | [`Weeks`](../api/functions/Weeks.md)                             | The weeks section in the month grid.                           |
 | [`YearsDropdown`](../api/functions/YearsDropdown.md)             | The dropdown with the years.                                   |
+| `Button`                                                         | Deprecated: use `NextMonthButton`/`PreviousMonthButton`.       |
 
 ## DayPicker Hook
 
@@ -160,14 +179,39 @@ export function MyDatePicker() {
   <Examples.CustomDayButton />
 </BrowserWindow>
 
+### Compose with the defaults
+
+When you want to add UI but keep the built-in behavior (focus, labels, modifier classes), wrap the default component from context.
+
+```tsx title="./WrappedDayButton.tsx"
+import { DayButtonProps, DayPicker, UI, useDayPicker } from "react-day-picker";
+
+function WrappedDayButton(props: DayButtonProps) {
+  const { components, classNames } = useDayPicker();
+  return (
+    <components.DayButton
+      {...props}
+      className={`${classNames[UI.DayButton]} my-custom-class`}
+    >
+      <span>{props.day.date.getDate()}</span>
+      <small aria-hidden>★</small>
+    </components.DayButton>
+  );
+}
+
+export function WrappedDayExample() {
+  return <DayPicker components={{ DayButton: WrappedDayButton }} />;
+}
+```
+
 ### Custom Select Dropdown
 
 You can use a custom [Dropdown](../api/functions/Dropdown.md) to select years and months. The example below uses a simplified version of `shadcn/ui`'s [Select](https://ui.shadcn.com/docs/components/select).
 
 ```tsx title="./CustomDropdown.tsx"
 import React, { useState } from "react";
 
-import { DayButtonProps, DayPicker } from "react-day-picker";
+import { DayPicker, type DropdownProps } from "react-day-picker";
 
 import {
   Select,
@@ -179,7 +223,7 @@ import {
 } from "@/components/ui/select";
 
 export function CustomSelectDropdown(props: DropdownProps) {
-  const { options, value, onChange } = props;
+  const { options, value, onChange, "aria-label": ariaLabel } = props;
 
   const handleValueChange = (newValue: string) => {
     if (onChange) {
@@ -195,7 +239,7 @@ export function CustomSelectDropdown(props: DropdownProps) {
 
   return (
     <Select value={value?.toString()} onValueChange={handleValueChange}>
-      <SelectTrigger>
+      <SelectTrigger aria-label={ariaLabel}>
         <SelectValue />
       </SelectTrigger>
       <SelectContent>
@@ -237,4 +281,33 @@ export function CustomDropdown() {
   <Examples.CustomDropdown />
 </BrowserWindow>
 
+If your design system portals dropdown content, provide the container (as shown in `examples/CustomDropdown/CustomDropdown.tsx`) so the list renders inside the calendar's shadow root in the docs.
+
+### Structural customization
+
+Swap layout components to add design-system wrappers or decoration while keeping behavior.
+
+```tsx title="./CustomRoot.tsx"
+import { DayPicker, type RootProps } from "react-day-picker";
+
+function CardRoot(props: RootProps) {
+  const { rootRef, ...rest } = props;
+  return (
+    <div ref={rootRef} className="card shadow-md" {...rest}>
+      {rest.children}
+    </div>
+  );
+}
+
+export function CustomRootExample() {
+  return <DayPicker components={{ Root: CardRoot }} />;
+}
+```
+
+### Choosing Day vs. DayButton vs. formatters
+
+- Use `DayButton` to change interactivity or add content inside the button while keeping the cell layout.
+- Use `Day` to change the table cell structure (wrappers, tooltips) when you need control over the `<td>`.
+- Use [formatters](./translation.mdx#custom-formatters) for simple text changes (e.g., labels) without altering structure.
+
 What are you using custom components for? [Let us know](https://github.com/gpbl/react-day-picker/discussions).