0
# Customization Options
1

2
React Day Picker provides extensive customization capabilities through component replacement, formatters, labels, and styling systems.
3

4
## Capabilities
5

6
### Custom Components System
7

8
Replace any UI element with custom React components while maintaining full functionality and accessibility.
9

10
```typescript { .api }
11
/**
12
 * The components that can be customized using the components prop
13
 */
14
type CustomComponents = {
15
  /** Render any button element in DayPicker (deprecated - use NextMonthButton or PreviousMonthButton instead) */
16
  Button: React.ComponentType<ButtonProps>;
17
  /** Render the chevron icon used in the navigation buttons and dropdowns */
18
  Chevron: React.ComponentType<ChevronProps>;
19
  /** Render the caption label of the month grid */
20
  CaptionLabel: React.ComponentType<CaptionLabelProps>;
21
  /** Render the day cell in the month grid */
22
  Day: React.ComponentType<DayProps>;
23
  /** Render the button containing the day in the day cell */
24
  DayButton: React.ComponentType<DayButtonProps>;
25
  /** Render the dropdown element to select years and months */
26
  Dropdown: React.ComponentType<DropdownProps>;
27
  /** Render the container of the dropdowns */
28
  DropdownNav: React.ComponentType<DropdownNavProps>;
29
  /** Render the footer element announced by screen readers */
30
  Footer: React.ComponentType<FooterProps>;
31
  /** Render the container of the MonthGrid */
32
  Month: React.ComponentType<MonthProps>;
33
  /** Render the caption of the month grid */
34
  MonthCaption: React.ComponentType<MonthCaptionProps>;
35
  /** Render the grid of days in a month */
36
  MonthGrid: React.ComponentType<MonthGridProps>;
37
  /** Wrapper of the month grids */
38
  Months: React.ComponentType<MonthsProps>;
39
  /** Render the navigation element with the next and previous buttons */
40
  Nav: React.ComponentType<NavProps>;
41
  /** Render the option HTML element in the dropdown */
42
  Option: React.ComponentType<OptionProps>;
43
  /** Render the previous month button element in the navigation */
44
  PreviousMonthButton: React.ComponentType<PreviousMonthButtonProps>;
45
  /** Render the next month button element in the navigation */
46
  NextMonthButton: React.ComponentType<NextMonthButtonProps>;
47
  /** Render the root element of the calendar */
48
  Root: React.ComponentType<RootProps>;
49
  /** Render the select element in the dropdowns */
50
  Select: React.ComponentType<SelectProps>;
51
  /** Render the weeks section in the month grid */
52
  Weeks: React.ComponentType<WeeksProps>;
53
  /** Render the week rows */
54
  Week: React.ComponentType<WeekProps>;
55
  /** Render the weekday name in the header */
56
  Weekday: React.ComponentType<WeekdayProps>;
57
  /** Render the row containing the week days */
58
  Weekdays: React.ComponentType<WeekdaysProps>;
59
  /** Render the cell with the number of the week */
60
  WeekNumber: React.ComponentType<WeekNumberProps>;
61
  /** Render the header of the week number column */
62
  WeekNumberHeader: React.ComponentType<WeekNumberHeaderProps>;
63
  /** Render the dropdown for selecting months */
64
  MonthsDropdown: React.ComponentType<MonthsDropdownProps>;
65
  /** Render the dropdown for selecting years */
66
  YearsDropdown: React.ComponentType<YearsDropdownProps>;
67
};
68
```
69

70
**Usage Examples:**
71

72
```typescript
73
import { DayPicker, type DayProps } from "react-day-picker";
74

75
// Custom day component with tooltip
76
function CustomDay({ day, modifiers, ...props }: DayProps) {
77
  const isWeekend = modifiers.weekend;
78
  
79
  return (
80
    <div 
81
      {...props}
82
      title={isWeekend ? "Weekend" : "Weekday"}
83
      style={{
84
        ...props.style,
85
        backgroundColor: isWeekend ? "#f0f0f0" : "white"
86
      }}
87
    >
88
      {props.children}
89
    </div>
90
  );
91
}
92

93
// Custom footer showing selection count
94
function CustomFooter() {
95
  const { selected, mode } = useDayPicker();
96
  const count = mode === "multiple" ? selected?.length || 0 : 0;
97
  
98
  return (
99
    <div style={{ padding: "10px", textAlign: "center" }}>
100
      {mode === "multiple" && `${count} dates selected`}
101
    </div>
102
  );
103
}
104

105
// Using custom components
106
<DayPicker
107
  mode="multiple"
108
  components={{
109
    Day: CustomDay,
110
    Footer: CustomFooter
111
  }}
112
  modifiers={{
113
    weekend: { dayOfWeek: [0, 6] }
114
  }}
115
/>
116
```
117

118
### Component Props Types
119

120
```typescript { .api }
121
interface DayProps {
122
  /** Calendar day data */
123
  day: CalendarDay;
124
  /** Day modifiers */
125
  modifiers: Modifiers;
126
  /** CSS class name */
127
  className?: string;
128
  /** Inline styles */
129
  style?: React.CSSProperties;
130
  /** Children elements */
131
  children?: React.ReactNode;
132
  /** Standard HTML attributes */
133
  [key: string]: any;
134
}
135

136
interface DayButtonProps {
137
  /** Calendar day data */
138
  day: CalendarDay;
139
  /** Day modifiers */
140
  modifiers: Modifiers;
141
  /** CSS class name */
142
  className?: string;
143
  /** Inline styles */
144
  style?: React.CSSProperties;
145
  /** Button type */
146
  type: "button";
147
  /** Disabled state */
148
  disabled?: boolean;
149
  /** Tab index */
150
  tabIndex?: number;
151
  /** Accessibility label */
152
  "aria-label"?: string;
153
  /** Click handler */
154
  onClick?: React.MouseEventHandler;
155
  /** Focus handler */
156
  onFocus?: React.FocusEventHandler;
157
  /** Blur handler */
158
  onBlur?: React.FocusEventHandler;
159
  /** Key down handler */
160
  onKeyDown?: React.KeyboardEventHandler;
161
  /** Mouse enter handler */
162
  onMouseEnter?: React.MouseEventHandler;
163
  /** Mouse leave handler */
164
  onMouseLeave?: React.MouseEventHandler;
165
  /** Children elements */
166
  children?: React.ReactNode;
167
}
168

169
interface MonthProps {
170
  /** Display index in multi-month view */
171
  displayIndex: number;
172
  /** Calendar month data */
173
  calendarMonth: CalendarMonth;
174
  /** CSS class name */
175
  className?: string;
176
  /** Inline styles */  
177
  style?: React.CSSProperties;
178
  /** Children elements */
179
  children?: React.ReactNode;
180
}
181

182
interface NavProps {
183
  /** CSS class name */
184
  className?: string;
185
  /** Inline styles */
186
  style?: React.CSSProperties;
187
  /** Accessibility label */
188
  "aria-label"?: string;
189
  /** Previous month click handler */
190
  onPreviousClick?: () => void;
191
  /** Next month click handler */
192
  onNextClick?: () => void;
193
  /** Previous month data */
194
  previousMonth?: Date;
195
  /** Next month data */
196
  nextMonth?: Date;
197
  /** Children elements */
198
  children?: React.ReactNode;
199
}
200
```
201

202
### Formatters System
203

204
Customize how dates and labels are displayed throughout the calendar.
205

206
```typescript { .api }
207
/**
208
 * Interface for custom date and text formatters
209
 */
210
interface Formatters {
211
  /** Format the month caption (e.g., "November 2024") */
212
  formatCaption: (
213
    month: Date,
214
    options?: DateLibOptions,
215
    dateLib?: DateLib
216
  ) => string;
217
  
218
  /** Format individual day numbers */
219
  formatDay: (
220
    date: Date,
221
    options?: DateLibOptions,
222
    dateLib?: DateLib
223
  ) => string;
224
  
225
  /** Format month names in dropdown */
226
  formatMonthDropdown: (month: Date, dateLib?: DateLib) => string;
227
  
228
  /** Format year values in dropdown */
229
  formatYearDropdown: (year: Date, dateLib?: DateLib) => string;
230
  
231
  /** Format weekday names in header */
232
  formatWeekdayName: (
233
    weekday: Date,
234
    options?: DateLibOptions,
235
    dateLib?: DateLib
236
  ) => string;
237
  
238
  /** Format week numbers */
239
  formatWeekNumber: (weekNumber: number, dateLib?: DateLib) => string;
240
  
241
  /** Format week number column header */
242
  formatWeekNumberHeader: () => string;
243
}
244
```
245

246
**Usage Examples:**
247

248
```typescript
249
const customFormatters: Partial<Formatters> = {
250
  formatCaption: (month, options, dateLib) => {
251
    return dateLib?.format(month, "MMMM yyyy", options) || "";
252
  },
253
  
254
  formatDay: (date, options, dateLib) => {
255
    // Add ordinal suffix to day numbers
256
    const day = dateLib?.getDate(date) || date.getDate();
257
    const suffix = getOrdinalSuffix(day);
258
    return `${day}${suffix}`;
259
  },
260
  
261
  formatWeekdayName: (weekday, options, dateLib) => {
262
    // Use single letter weekday names
263
    return dateLib?.format(weekday, "EEEEE", options) || "";
264
  }
265
};
266

267
function getOrdinalSuffix(day: number): string {
268
  if (day > 3 && day < 21) return "th";
269
  switch (day % 10) {
270
    case 1: return "st";
271
    case 2: return "nd"; 
272
    case 3: return "rd";
273
    default: return "th";
274
  }
275
}
276

277
<DayPicker formatters={customFormatters} />
278
```
279

280
### Labels System
281

282
Customize accessibility labels for screen readers and assistive technologies.
283

284
```typescript { .api }
285
/**
286
 * Interface for custom accessibility labels
287
 */
288
interface Labels {
289
  /** Label for day buttons */
290
  labelDayButton: (
291
    date: Date,
292
    modifiers: Modifiers,
293
    options?: DateLibOptions,
294
    dateLib?: DateLib
295
  ) => string;
296
  
297
  /** Label for the calendar grid */
298
  labelGrid: (
299
    month: Date,
300
    options?: DateLibOptions,
301
    dateLib?: DateLib
302
  ) => string;
303
  
304
  /** Label for non-interactive grid cells */
305
  labelGridcell: (
306
    date: Date,
307
    modifiers: Modifiers,
308
    options?: DateLibOptions,
309
    dateLib?: DateLib
310
  ) => string;
311
  
312
  /** Label for month dropdown */
313
  labelMonthDropdown: () => string;
314
  
315
  /** Label for year dropdown */
316
  labelYearDropdown: (options?: DateLibOptions) => string;
317
  
318
  /** Label for navigation toolbar */
319
  labelNav: () => string;
320
  
321
  /** Label for next month button */
322
  labelNext: (month?: Date) => string;
323
  
324
  /** Label for previous month button */
325
  labelPrevious: (month?: Date) => string;
326
  
327
  /** Label for weekday headers */
328
  labelWeekday: (
329
    weekday: Date,
330
    options?: DateLibOptions,
331
    dateLib?: DateLib
332
  ) => string;
333
  
334
  /** Label for week numbers */
335
  labelWeekNumber: (
336
    weekNumber: number,
337
    options?: { locale?: Locale }
338
  ) => string;
339
  
340
  /** Label for week number header */
341
  labelWeekNumberHeader: (options?: DateLibOptions) => string;
342
}
343
```
344

345
**Usage Examples:**
346

347
```typescript
348
const customLabels: Partial<Labels> = {
349
  labelDayButton: (date, modifiers) => {
350
    const dayName = date.toLocaleDateString("en-US", { weekday: "long" });
351
    const monthName = date.toLocaleDateString("en-US", { month: "long" });
352
    const day = date.getDate();
353
    const year = date.getFullYear();
354
    
355
    let label = `${dayName}, ${monthName} ${day}, ${year}`;
356
    
357
    if (modifiers.selected) label += " (selected)";
358
    if (modifiers.disabled) label += " (disabled)";
359
    if (modifiers.today) label += " (today)";
360
    
361
    return label;
362
  },
363
  
364
  labelNext: (month) => {
365
    if (!month) return "Go to next month";
366
    const monthName = month.toLocaleDateString("en-US", { month: "long" });
367
    const year = month.getFullYear();
368
    return `Go to ${monthName} ${year}`;
369
  },
370
  
371
  labelPrevious: (month) => {
372
    if (!month) return "Go to previous month";
373
    const monthName = month.toLocaleDateString("en-US", { month: "long" });
374
    const year = month.getFullYear();
375
    return `Go to ${monthName} ${year}`;
376
  }
377
};
378

379
<DayPicker labels={customLabels} />
380
```
381

382
### Data Classes
383

384
Core data structures used throughout the customization system.
385

386
```typescript { .api }
387
/**
388
 * Represents a day in the calendar
389
 */
390
class CalendarDay {
391
  /** The date this day represents */
392
  date: Date;
393
  /** The month this day is displayed in */
394
  displayMonth: Date;
395
  /** Whether this day is outside the display month */
396
  outside: boolean;
397
  /** DateLib instance for date operations */
398
  dateLib: DateLib;
399
  
400
  constructor(date: Date, displayMonth: Date, dateLib?: DateLib);
401
  
402
  /** Check if this day is equal to another day */
403
  isEqualTo(day: CalendarDay): boolean;
404
}
405

406
/**
407
 * Represents a week in the calendar
408
 */
409
class CalendarWeek {
410
  /** Week number in the year */
411
  weekNumber: number;
412
  /** Array of days in this week */
413
  days: CalendarDay[];
414
  
415
  constructor(weekNumber: number, days: CalendarDay[]);
416
}
417

418
/**
419
 * Represents a month in the calendar
420
 */
421
class CalendarMonth {
422
  /** The date representing this month */
423
  date: Date;
424
  /** Array of weeks in this month */
425
  weeks: CalendarWeek[];
426
  
427
  constructor(date: Date, weeks: CalendarWeek[]);
428
}
429
```