docs: expand custom selections guide with runnable examples

Author: gpbl

examples/CustomMonthSelection.tsx

@@ -0,0 +1,36 @@
+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
+      mode="default"
+      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,38 @@
+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
+      mode="default"
+      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/index.ts

@@ -18,6 +18,8 @@ export * from "./CustomDropdown";
 export * from "./CustomMultiple";
 export * from "./CustomSingle";
 export * from "./CustomWeek";
+export * from "./CustomRollingWindow";
+export * from "./CustomMonthSelection";
 export * from "./DefaultMonth";
 export * from "./Dialog";
 export * from "./Disabled";

website/docs/guides/custom-selections.mdx

@@ -4,12 +4,6 @@ sidebar_position: 2
 
 # Custom Selections
 
-:::info Draft
-
-This documentation is still a work in progress. If you have any questions, please visit the [discussions](https://github.com/gpbl/react-day-picker/discussions) page on GitHub.
-
-:::
-
 If the built-in [selection modes](../selections/selection-modes.mdx) do not satisfy your app’s requirements, you can control the selection behavior using the [`onDayClick`](../api/interfaces/PropsBase.md#ondayclick) and [`modifiers`](../api/type-aliases/Modifiers.md) props.
 
 | Prop         | Type                                                        | Description                               |
@@ -19,6 +13,13 @@ If the built-in [selection modes](../selections/selection-modes.mdx) do not sati
 
 The `onDayClick` prop is a function that receives the clicked day and its modifiers as arguments.
 
+## How custom selection works
+
+- Use `mode="default"` (or omit `mode`) to disable built-in selection logic.
+- Keep your own selection state, derive a `selected` modifier (and any `range_*` modifiers) from it, and pass them to `modifiers` so styling/ARIA stay aligned.
+- Ignore clicks on `modifiers.disabled` or `modifiers.hidden` to preserve accessibility.
+- For keyboard support, handle `onDayKeyDown` (Space/Enter) in the same way as `onDayClick`.
+
 ## Examples
 
 ### Week Selection
@@ -31,35 +32,53 @@ Note the use of the `startOfWeek` and `endOfWeek` functions from [date-fns](http
 import React, { useState } from "react";
 
 import { endOfWeek, startOfWeek } from "date-fns";
-import { DateRange, DayPicker, isDateInRange } from "react-day-picker";
+import {
+  type DateRange,
+  DayPicker,
+  rangeIncludesDate,
+} from "react-day-picker";
 
 /** Select the whole week when the day is clicked. */
 export function CustomWeek() {
   const [selectedWeek, setSelectedWeek] = useState<DateRange | undefined>();
 
   return (
     <DayPicker
+      mode="default"
       showWeekNumber
       showOutsideDays
       modifiers={{
         selected: selectedWeek,
         range_start: selectedWeek?.from,
         range_end: selectedWeek?.to,
         range_middle: (date: Date) =>
-          selectedWeek
-            ? isDateInRange(date, selectedWeek, { excludeEnds: true })
-            : false,
+          selectedWeek ? rangeIncludesDate(selectedWeek, date, true) : false,
       }}
       onDayClick={(day, modifiers) => {
+        if (modifiers.disabled || modifiers.hidden) return;
         if (modifiers.selected) {
-          setSelectedWeek(undefined); // Clear the selection if the day is already selected
+          setSelectedWeek(undefined);
           return;
         }
         setSelectedWeek({
           from: startOfWeek(day),
           to: endOfWeek(day),
         });
       }}
+      onDayKeyDown={(day, modifiers, e) => {
+        if (e.key === " " || e.key === "Enter") {
+          e.preventDefault();
+          if (modifiers.disabled || modifiers.hidden) return;
+          if (modifiers.selected) {
+            setSelectedWeek(undefined);
+            return;
+          }
+          setSelectedWeek({
+            from: startOfWeek(day),
+            to: endOfWeek(day),
+          });
+        }
+      }}
       footer={
         selectedWeek &&
         `Week from ${selectedWeek?.from?.toLocaleDateString()} to ${selectedWeek?.to?.toLocaleDateString()}`
@@ -91,12 +110,17 @@ export function CustomSingle() {
   }
   return (
     <DayPicker
+      mode="default"
       modifiers={modifiers}
       onDayClick={(day, modifiers) => {
-        if (modifiers.selected) {
-          setSelectedDate(undefined);
-        } else {
-          setSelectedDate(day);
+        if (modifiers.disabled || modifiers.hidden) return;
+        setSelectedDate(modifiers.selected ? undefined : day);
+      }}
+      onDayKeyDown={(day, modifiers, e) => {
+        if (e.key === " " || e.key === "Enter") {
+          e.preventDefault();
+          if (modifiers.disabled || modifiers.hidden) return;
+          setSelectedDate(modifiers.selected ? undefined : day);
         }
       }}
       footer={selectedDate && `You selected ${selectedDate.toDateString()}`}
@@ -117,18 +141,24 @@ Selecting multiple days is a bit more complex as it involves handling an array o
 import { useState } from "react";
 
 import { isSameDay } from "date-fns";
-import { DayMouseEventHandler, DayPicker } from "react-day-picker";
+import { DayEventHandler, DayPicker } from "react-day-picker";
 
 export function CustomMultiple() {
   const [value, setValue] = useState<Date[]>([]);
 
-  const handleDayClick: DayMouseEventHandler = (day, modifiers) => {
+  const handleDayClick: DayEventHandler<React.MouseEvent> = (
+    day,
+    modifiers,
+  ) => {
+    if (modifiers.disabled || modifiers.hidden) return;
     const newValue = [...value];
     if (modifiers.selected) {
       const index = value.findIndex((d) => isSameDay(day, d));
       newValue.splice(index, 1);
     } else {
-      newValue.push(day);
+      if (!value.some((d) => isSameDay(d, day))) {
+        newValue.push(day);
+      }
     }
     setValue(newValue);
   };
@@ -141,13 +171,22 @@ export function CustomMultiple() {
     footer = (
       <>
         You selected {value.length} days.{" "}
-        <button onClick={handleResetClick}>Reset</button>
+        <button type="button" onClick={handleResetClick}>
+          Reset
+        </button>
       </>
     );
 
   return (
     <DayPicker
+      mode="default"
       onDayClick={handleDayClick}
+      onDayKeyDown={(day, modifiers, e) => {
+        if (e.key === " " || e.key === "Enter") {
+          e.preventDefault();
+          handleDayClick(day, modifiers, e as any);
+        }
+      }}
       modifiers={{ selected: value }}
       footer={footer}
     />
@@ -158,3 +197,145 @@ export function CustomMultiple() {
 <BrowserWindow>
   <Examples.CustomMultiple />
 </BrowserWindow>
+
+### Rolling N-day window
+
+Create a fixed-length range (for example, 7 days) starting from the clicked day.
+
+```tsx
+import { addDays } from "date-fns";
+import { useState } from "react";
+
+import { type DateRange, DayPicker } from "react-day-picker";
+
+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
+      mode="default"
+      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));
+        }
+      }}
+    />
+  );
+}
+```
+
+<BrowserWindow>
+  <Examples.CustomRollingWindow />
+</BrowserWindow>
+
+### Selecting full months
+
+Toggle an entire month at a time.
+
+```tsx
+import { endOfMonth, startOfMonth } from "date-fns";
+import { useState } from "react";
+
+import { type DateRange, DayPicker } from "react-day-picker";
+
+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
+      mode="default"
+      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));
+      }}
+    />
+  );
+}
+```
+
+<BrowserWindow>
+  <Examples.CustomMonthSelection />
+</BrowserWindow>
+
+## Style custom modifiers
+
+Use `modifiersClassNames` or `modifiersStyles` to surface your custom state (for example, `range_middle`, `rolling`, `blocked`).
+
+```tsx
+<DayPicker
+  mode="default"
+  modifiers={{ selected: value, rolling: rollingRange }}
+  modifiersClassNames={{ rolling: "my-rolling" }}
+  modifiersStyles={{ rolling: { background: "var(--rdp-accent-color)" } }}
+/>
+```
+
+## Week numbers and starts
+
+For week-based selections, set `weekStartsOn` (locale-aware) and consider handling `onWeekNumberClick` to select a week when its number is clicked. Combine it with `showWeekNumber`.
+
+```tsx
+<DayPicker
+  mode="default"
+  showWeekNumber
+  weekStartsOn={1}
+  onWeekNumberClick={(weekNumber, week, e) => {
+    e.preventDefault();
+    setSelectedWeek({ from: week.from, to: week.to });
+  }}
+  modifiers={{ selected: selectedWeek }}
+/>
+```
+
+## Persisting custom selections
+
+Serialize your custom selection state before storing or sending it.
+
+```ts
+// Single date
+const payload = selectedDate ? selectedDate.toISOString() : null;
+
+// Multiple dates
+const payload = value.map((date) => date.toISOString());
+
+// Range
+const payload =
+  range?.from && range?.to
+    ? { from: range.from.toISOString(), to: range.to.toISOString() }
+    : null;
+```