0
# Main Component Configuration
1

2
The `DayPicker` component is the main React component that renders a customizable calendar interface. It accepts extensive configuration options through props to control appearance, behavior, and functionality.
3

4
## Capabilities
5

6
### DayPicker Component
7

8
The primary React component for rendering date picker calendars.
9

10
```typescript { .api }
11
/**
12
 * Renders the DayPicker calendar component
13
 * @param props - Configuration props for the DayPicker component
14
 * @returns Rendered DayPicker React element
15
 */
16
function DayPicker(props: DayPickerProps): React.ReactElement;
17

18
type DayPickerProps = PropsBase & (
19
  | PropsSingle
20
  | PropsSingleRequired  
21
  | PropsMulti
22
  | PropsMultiRequired
23
  | PropsRange
24
  | PropsRangeRequired
25
  | { mode?: undefined; required?: undefined }
26
);
27
```
28

29
**Usage Examples:**
30

31
```typescript
32
import { DayPicker } from "react-day-picker";
33
import "react-day-picker/style.css";
34

35
// Basic calendar without selection
36
function BasicCalendar() {
37
  return <DayPicker />;
38
}
39

40
// Calendar with custom initial month
41
function CustomInitialMonth() {
42
  return (
43
    <DayPicker
44
      defaultMonth={new Date(2024, 5)}
45
      fromDate={new Date(2024, 0)}
46
      toDate={new Date(2024, 11)}
47
    />
48
  );
49
}
50

51
// Calendar with disabled dates
52
function CalendarWithDisabledDates() {
53
  const disabledDays = [
54
    new Date(2024, 5, 10),
55
    new Date(2024, 5, 20),
56
    { before: new Date(2024, 5, 1) },
57
    { dayOfWeek: [0, 6] } // weekends
58
  ];
59

60
  return (
61
    <DayPicker
62
      disabled={disabledDays}
63
      modifiersClassNames={{
64
        disabled: "my-disabled-day"
65
      }}
66
    />
67
  );
68
}
69
```
70

71
### Base Props Interface
72

73
Core configuration props available to all DayPicker variants.
74

75
```typescript { .api }
76
/**
77
 * Base props for customizing the calendar, handling localization, and managing events
78
 */
79
interface PropsBase {
80
  /** Class name to add to the root element */
81
  className?: string;
82
  /** Change the class names used by DayPicker */
83
  classNames?: Partial<ClassNames>;
84
  /** Change the class name for days matching the modifiers */
85
  modifiersClassNames?: ModifiersClassNames;
86
  /** Style to apply to the root element */
87
  style?: React.CSSProperties;
88
  /** Change the inline styles of the HTML elements */
89
  styles?: Partial<Styles>;
90
  /** Change the style for days matching the modifiers */
91
  modifiersStyles?: ModifiersStyles;
92
  /** A unique id to add to the root element */
93
  id?: string;
94
  
95
  /** The initial month to show in the calendar */
96
  defaultMonth?: Date;
97
  /** The month displayed in the calendar (controlled) */
98
  month?: Date;
99
  /** Event handler when the month changes */
100
  onMonthChange?: (month: Date) => void;
101
  
102
  /** The number of months to display */
103
  numberOfMonths?: number;
104
  /** Enable paged navigation */
105
  pagedNavigation?: boolean;
106
  /** Reverse the years in the dropdown */
107
  reverseYears?: boolean;
108
  
109
  /** The earliest month to start the month navigation */
110
  startMonth?: Date;
111
  /** The latest month to end the month navigation */
112
  endMonth?: Date;
113
  /** The earliest day to start the day navigation */
114
  fromDate?: Date;
115
  /** The latest day to end the day navigation */
116
  toDate?: Date;
117
  
118
  /** Hide the navigation bar */
119
  hideNavigation?: boolean;
120
  /** Disable the navigation */
121
  disableNavigation?: boolean;
122
  /** The layout of the navigation */
123
  navLayout?: "before" | "after" | "around";
124
  /** The layout of the caption */
125
  captionLayout?: "label" | "dropdown" | "dropdown-months" | "dropdown-years";
126
  
127
  /** Show the week numbers */
128
  showWeekNumber?: boolean;
129
  /** Hide the weekdays row */
130
  hideWeekdays?: boolean;
131
  /** Show the outside days */
132
  showOutsideDays?: boolean;
133
  /** Make outside days non-interactive */
134
  fixedWeeks?: boolean;
135
  
136
  /** Use ISO 8601 week dates */
137
  ISOWeek?: boolean;
138
  /** Use broadcast calendar */
139
  broadcastCalendar?: boolean;
140
  /** The day of week to start the week */
141
  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
142
  /** The day of January which is always in the first week */
143
  firstWeekContainsDate?: 1 | 2 | 3 | 4 | 5 | 6 | 7;
144
  
145
  /** Today's date (defaults to current date) */
146
  today?: Date;
147
  /** The locale object to localize the user interface */
148
  locale?: Locale;
149
  /** Time zone to display the dates */
150
  timeZone?: string;
151
  /** Custom date library */
152
  dateLib?: Partial<DateLib>;
153
  
154
  /** Apply modifiers to days matching the given matchers */
155
  modifiers?: Record<string, Matcher>;
156
  /** Hide days matching the given matchers */
157
  hidden?: Matcher | Matcher[];
158
  /** Disable days matching the given matchers */
159
  disabled?: Matcher | Matcher[];
160
  
161
  /** Custom components to replace the default ones */
162
  components?: CustomComponents;
163
  /** Custom formatters for date display */
164
  formatters?: Partial<Formatters>;
165
  /** Custom labels for accessibility */
166
  labels?: Partial<Labels>;
167
  
168
  /** Enable month change animation */
169
  animate?: boolean;
170
  /** Text direction */
171
  dir?: "ltr" | "rtl";
172
  /** Language tag */
173
  lang?: string;
174
  /** The role attribute */
175
  role?: string;
176
  /** The aria-label attribute */
177
  "aria-label"?: string;
178
  /** Content Security Policy nonce */
179
  nonce?: string;
180
  /** The title attribute */
181
  title?: string;
182
  
183
  /** Event handler for when a day button loses focus */
184
  onDayBlur?: DayEventHandler<React.FocusEvent>;
185
  /** Event handler for when a day is clicked */
186
  onDayClick?: DayEventHandler<React.MouseEvent>;
187
  /** Event handler for when a day button receives focus */
188
  onDayFocus?: DayEventHandler<React.FocusEvent>;
189
  /** Event handler for when a key is pressed on a day button */
190
  onDayKeyDown?: DayEventHandler<React.KeyboardEvent>;
191
  /** Event handler for when the mouse enters a day button */
192
  onDayMouseEnter?: DayEventHandler<React.MouseEvent>;
193
  /** Event handler for when the mouse leaves a day button */
194
  onDayMouseLeave?: DayEventHandler<React.MouseEvent>;
195
  /** Event handler for when the next month button is clicked */
196
  onNextClick?: MonthChangeEventHandler;
197
  /** Event handler for when the previous month button is clicked */
198
  onPrevClick?: MonthChangeEventHandler;
199
  
200
  /** Custom content to display in the footer */
201
  footer?: React.ReactNode;
202
  /** Custom numerals for date display */
203
  numerals?: Numerals;
204
  /** Use additional week year tokens */
205
  useAdditionalWeekYearTokens?: boolean;
206
  /** Use additional day of year tokens */
207
  useAdditionalDayOfYearTokens?: boolean;
208
}
209
```
210

211
### Event Handler Types
212

213
```typescript { .api }
214
/**
215
 * Generic day event handler for various mouse and keyboard events
216
 */
217
type DayEventHandler<EventType extends React.SyntheticEvent> = (
218
  date: Date,
219
  modifiers: Modifiers,
220
  e: EventType
221
) => void;
222

223
/**
224
 * Event handler for month navigation events
225
 */
226
type MonthChangeEventHandler = (month: Date) => void;
227

228
/**
229
 * Record of modifier flags applied to a day
230
 */
231
interface Modifiers {
232
  [modifier: string]: boolean;
233
}
234
```
235

236
### Matcher System
237

238
System for specifying which dates should receive certain modifiers or behaviors.
239

240
```typescript { .api }
241
/**
242
 * Union type for various date matching patterns
243
 */
244
type Matcher = 
245
  | boolean
246
  | ((date: Date) => boolean)
247
  | Date
248
  | Date[]
249
  | DateRange
250
  | DateInterval
251
  | DateBefore
252
  | DateAfter
253
  | DayOfWeek;
254

255
interface DateRange {
256
  from: Date | undefined;
257
  to: Date | undefined;
258
}
259

260
interface DateInterval {
261
  before: Date;
262
  after: Date;
263
}
264

265
interface DateBefore {
266
  before: Date;
267
}
268

269
interface DateAfter {
270
  after: Date;
271
}
272

273
interface DayOfWeek {
274
  dayOfWeek: number | number[];
275
}
276
```
277

278
**Usage Examples:**
279

280
```typescript
281
// Disable specific dates
282
const disabledMatcher: Matcher[] = [
283
  new Date(2024, 5, 15), // specific date
284
  { before: new Date(2024, 5, 1) }, // dates before June 1st
285
  { after: new Date(2024, 5, 30) }, // dates after June 30th
286
  { dayOfWeek: [0, 6] }, // weekends
287
  (date: Date) => date.getDate() > 25 // custom function
288
];
289

290
<DayPicker disabled={disabledMatcher} />
291

292
// Custom modifiers
293
const customModifiers = {
294
  weekend: { dayOfWeek: [0, 6] },
295
  holiday: [
296
    new Date(2024, 6, 4), // July 4th
297
    new Date(2024, 11, 25) // Christmas
298
  ],
299
  available: (date: Date) => date.getDate() % 2 === 0
300
};
301

302
<DayPicker 
303
  modifiers={customModifiers}
304
  modifiersClassNames={{
305
    weekend: "weekend-day",
306
    holiday: "holiday-day",
307
    available: "available-day"
308
  }}
309
/>
310
```