0
# Core Functionality
1

2
The DatePicker component provides comprehensive date and time selection capabilities with extensive customization options, accessibility features, and advanced filtering.
3

4
## Capabilities
5

6
### DatePicker Component
7

8
The main React component for date selection with support for single dates, date ranges, multiple dates, and time selection.
9

10
```typescript { .api }
11
/**
12
 * Main DatePicker component providing comprehensive date selection interface
13
 * Supports single dates, ranges, multiple selection, time picking, and extensive customization
14
 */
15
function DatePicker(props: DatePickerProps): React.ReactElement;
16

17
interface DatePickerProps {
18
  // Core date selection
19
  selected?: Date | null;
20
  onChange?: (
21
    date: Date | null | [Date | null, Date | null] | Date[], 
22
    event?: React.MouseEvent | React.KeyboardEvent
23
  ) => void;
24
  
25
  // Selection modes
26
  selectsRange?: boolean;
27
  selectsMultiple?: boolean;
28
  
29
  // Date range specific
30
  startDate?: Date | null;
31
  endDate?: Date | null;
32
  swapRange?: boolean;
33
  
34
  // Multiple selection specific  
35
  selectedDates?: Date[];
36
  
37
  // Date constraints
38
  minDate?: Date;
39
  maxDate?: Date;
40
  excludeDates?: Date[];
41
  includeDates?: Date[];
42
  excludeDateIntervals?: Array<{start: Date, end: Date}>;
43
  includeDateIntervals?: Array<{start: Date, end: Date}>;
44
  filterDate?: (date: Date) => boolean;
45
  
46
  // Display and formatting
47
  dateFormat?: string | string[];
48
  dateFormatCalendar?: string;
49
  locale?: Locale;
50
  inline?: boolean;
51
  fixedHeight?: boolean;
52
  
53
  // Time selection
54
  showTimeSelect?: boolean;
55
  showTimeSelectOnly?: boolean;
56
  showTimeInput?: boolean;
57
  timeFormat?: string;
58
  timeIntervals?: number;
59
  minTime?: Date;
60
  maxTime?: Date;
61
  excludeTimes?: Date[];
62
  includeTimes?: Date[];
63
  injectTimes?: Date[];
64
  filterTime?: (time: Date) => boolean;
65
  timeCaption?: string;
66
  timeInputLabel?: string;
67
  
68
  // Calendar display options
69
  showMonthDropdown?: boolean;
70
  showYearDropdown?: boolean;
71
  showMonthYearDropdown?: boolean;
72
  showFullMonthYearPicker?: boolean;
73
  showTwoColumnMonthYearPicker?: boolean;
74
  showFourColumnMonthYearPicker?: boolean;
75
  showYearPicker?: boolean;
76
  showQuarterYearPicker?: boolean;
77
  showWeekPicker?: boolean;
78
  showWeekNumbers?: boolean;
79
  weekLabel?: string;
80
  
81
  // Month/Year navigation
82
  monthsShown?: number;
83
  dropdownMode?: "scroll" | "select";
84
  yearItemNumber?: number;
85
  minYear?: number;
86
  maxYear?: number;
87
  
88
  // Highlighting and special dates
89
  highlightDates?: Array<Date | HighlightDate>;
90
  holidays?: Holiday[];
91
  
92
  // Interaction behavior
93
  shouldCloseOnSelect?: boolean;
94
  preventOpenOnFocus?: boolean;
95
  openToDate?: Date;
96
  startOpen?: boolean;
97
  allowSameDay?: boolean;
98
  selectsDisabledDaysInRange?: boolean;
99
  adjustDateOnChange?: boolean;
100
  
101
  // Accessibility
102
  ariaLabelledBy?: string;
103
  ariaDescribedBy?: string;
104
  ariaRequired?: string;
105
  ariaInvalid?: string;
106
  ariaLabelClose?: string;
107
  
108
  // Form integration
109
  id?: string;
110
  name?: string;
111
  required?: boolean;
112
  disabled?: boolean;
113
  readOnly?: boolean;
114
  autoComplete?: string;
115
  autoFocus?: boolean;
116
  tabIndex?: number;
117
  form?: string;
118
  title?: string;
119
  placeholderText?: string;
120
  value?: string;
121
  
122
  // Events
123
  onFocus?: (event: React.FocusEvent) => void;
124
  onBlur?: (event: React.FocusEvent) => void;
125
  onKeyDown?: (event: React.KeyboardEvent) => void;
126
  onClick?: () => void;
127
  onInputClick?: () => void;
128
  onSelect?: (date: Date | null, event?: React.SyntheticEvent) => void;
129
  onChangeRaw?: (event?: React.SyntheticEvent) => void;
130
  onCalendarOpen?: () => void;
131
  onCalendarClose?: () => void;
132
  onClickOutside?: (event: MouseEvent) => void;
133
  onInputError?: (error: {code: number, msg: string}) => void;
134
  
135
  // Styling and customization
136
  className?: string;
137
  wrapperClassName?: string;
138
  calendarClassName?: string;
139
  popperClassName?: string;
140
  dayClassName?: (date: Date) => string | null;
141
  weekDayClassName?: (date: Date) => string | null;
142
  monthClassName?: (date: Date) => string | null;
143
  timeClassName?: (time: Date) => string | null;
144
  
145
  // Custom components
146
  customInput?: React.ReactElement;
147
  customInputRef?: string;
148
  calendarContainer?: React.ComponentType;
149
  customTimeInput?: React.ComponentType;
150
  renderCustomHeader?: (params: ReactDatePickerCustomHeaderProps) => React.ReactNode;
151
  renderDayContents?: (dayOfMonth: number, date: Date) => React.ReactNode;
152
  
153
  // Portal and positioning
154
  withPortal?: boolean;
155
  portalId?: string;
156
  popperContainer?: React.ComponentType;
157
  popperPlacement?: string;
158
  popperModifiers?: object[];
159
  hidePopper?: boolean;
160
  showPopperArrow?: boolean;
161
  
162
  // Icon and clearing
163
  showIcon?: boolean;
164
  icon?: React.ReactNode;
165
  calendarIconClassName?: string;
166
  toggleCalendarOnIconClick?: boolean;
167
  isClearable?: boolean;
168
  clearButtonTitle?: string;
169
  clearButtonClassName?: string;
170
  
171
  // Advanced options
172
  closeOnScroll?: boolean | ((event: Event) => boolean);
173
  enableTabLoop?: boolean;
174
  disabledKeyboardNavigation?: boolean;
175
  calendarStartDay?: number;
176
  usePointerEvent?: boolean;
177
  excludeScrollbar?: boolean;
178
  useWeekdaysShort?: boolean;
179
  formatWeekDay?: (day: string) => string;
180
  strictParsing?: boolean;
181
  monthSelectedIn?: number;
182
  focusSelectedMonth?: boolean;
183
  showPreviousMonths?: boolean;
184
  
185
  // Navigation labels (for accessibility)
186
  previousMonthAriaLabel?: string;
187
  previousMonthButtonLabel?: string;
188
  nextMonthAriaLabel?: string;
189
  nextMonthButtonLabel?: string;
190
  previousYearAriaLabel?: string;
191
  previousYearButtonLabel?: string;
192
  nextYearAriaLabel?: string;
193
  nextYearButtonLabel?: string;
194
  
195
  // Children (for calendar content)
196
  children?: React.ReactNode;
197
}
198
```
199

200
**Usage Examples:**
201

202
```typescript
203
import React, { useState } from "react";
204
import DatePicker from "react-datepicker";
205
import "react-datepicker/dist/react-datepicker.css";
206

207
// Basic single date picker
208
function BasicDatePicker() {
209
  const [startDate, setStartDate] = useState<Date | null>(new Date());
210
  
211
  return (
212
    <DatePicker
213
      selected={startDate}
214
      onChange={(date) => setStartDate(date)}
215
      dateFormat="MM/dd/yyyy"
216
      placeholderText="Select a date"
217
    />
218
  );
219
}
220

221
// Date range picker
222
function DateRangePicker() {
223
  const [startDate, setStartDate] = useState<Date | null>(null);
224
  const [endDate, setEndDate] = useState<Date | null>(null);
225

226
  return (
227
    <DatePicker
228
      selected={startDate}
229
      onChange={(dates: [Date | null, Date | null]) => {
230
        const [start, end] = dates;
231
        setStartDate(start);
232
        setEndDate(end);
233
      }}
234
      startDate={startDate}
235
      endDate={endDate}
236
      selectsRange
237
      placeholderText="Select date range"
238
    />
239
  );
240
}
241

242
// Multiple date selection
243
function MultipleDatePicker() {
244
  const [selectedDates, setSelectedDates] = useState<Date[]>([]);
245

246
  return (
247
    <DatePicker
248
      selectedDates={selectedDates}
249
      onChange={(dates: Date[]) => setSelectedDates(dates)}
250
      selectsMultiple
251
      shouldCloseOnSelect={false}
252
      placeholderText="Select multiple dates"
253
    />
254
  );
255
}
256

257
// Date and time picker
258
function DateTimePicker() {
259
  const [startDate, setStartDate] = useState<Date | null>(new Date());
260

261
  return (
262
    <DatePicker
263
      selected={startDate}
264
      onChange={(date) => setStartDate(date)}
265
      showTimeSelect
266
      timeFormat="HH:mm"
267
      timeIntervals={15}
268
      timeCaption="Time"
269
      dateFormat="MM/dd/yyyy HH:mm"
270
    />
271
  );
272
}
273

274
// Inline calendar
275
function InlineCalendar() {
276
  const [startDate, setStartDate] = useState<Date | null>(new Date());
277

278
  return (
279
    <DatePicker
280
      selected={startDate}
281
      onChange={(date) => setStartDate(date)}
282
      inline
283
    />
284
  );
285
}
286

287
// Custom input
288
function CustomInputExample() {
289
  const [startDate, setStartDate] = useState<Date | null>(null);
290
  
291
  const CustomInput = React.forwardRef<HTMLButtonElement, any>(
292
    ({ value, onClick }, ref) => (
293
      <button className="custom-input" onClick={onClick} ref={ref}>
294
        {value || "Click to select date"}
295
      </button>
296
    )
297
  );
298

299
  return (
300
    <DatePicker
301
      selected={startDate}
302
      onChange={(date) => setStartDate(date)}
303
      customInput={<CustomInput />}
304
    />
305
  );
306
}
307

308
// Advanced filtering
309
function FilteredDatePicker() {
310
  const [startDate, setStartDate] = useState<Date | null>(null);
311
  
312
  // Only allow weekdays
313
  const isWeekday = (date: Date) => {
314
    const day = date.getDay();
315
    return day !== 0 && day !== 6;
316
  };
317

318
  return (
319
    <DatePicker
320
      selected={startDate}
321
      onChange={(date) => setStartDate(date)}
322
      filterDate={isWeekday}
323
      placeholderText="Select a weekday"
324
    />
325
  );
326
}
327
```
328

329
### CalendarContainer Component
330

331
Provides a customizable container for the calendar with proper ARIA attributes and accessibility features.
332

333
```typescript { .api }
334
/**
335
 * Container component for calendar with accessibility support
336
 * Provides proper ARIA roles and labels for screen reader compatibility
337
 */
338
function CalendarContainer(props: CalendarContainerProps): React.ReactElement;
339

340
interface CalendarContainerProps extends React.HTMLAttributes<HTMLDivElement> {
341
  showTimeSelectOnly?: boolean;
342
  showTime?: boolean;
343
  children?: React.ReactNode;
344
}
345
```
346

347
**Usage Example:**
348

349
```typescript
350
import { CalendarContainer } from "react-datepicker";
351

352
function CustomCalendarContainer({ className, children, ...props }) {
353
  return (
354
    <div className={`custom-calendar-wrapper ${className}`}>
355
      <CalendarContainer {...props}>
356
        <div className="calendar-header">Custom Header</div>
357
        {children}
358
        <div className="calendar-footer">Custom Footer</div>
359
      </CalendarContainer>
360
    </div>
361
  );
362
}
363

364
// Use with DatePicker
365
function DatePickerWithCustomContainer() {
366
  const [date, setDate] = useState<Date | null>(null);
367
  
368
  return (
369
    <DatePicker
370
      selected={date}
371
      onChange={setDate}
372
      calendarContainer={CustomCalendarContainer}
373
    />
374
  );
375
}
376
```
377

378
### Custom Header Interface  
379

380
Props interface for creating custom calendar headers with full navigation and state information.
381

382
```typescript { .api }
383
/**
384
 * Props interface for custom calendar header components
385
 * Provides access to calendar state and navigation functions
386
 */
387
interface ReactDatePickerCustomHeaderProps {
388
  /** Current calendar date */
389
  date: Date;
390
  /** Number of custom headers (for multi-month displays) */
391
  customHeaderCount: number;  
392
  /** Current month date */
393
  monthDate: Date;
394
  /** Function to change month (0-11) */
395
  changeMonth: (month: number) => void;
396
  /** Function to change year */
397
  changeYear: (year: number) => void;
398
  /** Function to go to previous month */
399
  decreaseMonth: () => void;
400
  /** Function to go to next month */
401
  increaseMonth: () => void;
402
  /** Function to go to previous year */
403
  decreaseYear: () => void;
404
  /** Function to go to next year */
405
  increaseYear: () => void;
406
  /** Whether previous month navigation is disabled */
407
  prevMonthButtonDisabled: boolean;
408
  /** Whether next month navigation is disabled */
409
  nextMonthButtonDisabled: boolean;
410
  /** Whether previous year navigation is disabled */
411
  prevYearButtonDisabled: boolean;
412
  /** Whether next year navigation is disabled */
413
  nextYearButtonDisabled: boolean;
414
  /** Visible years range for year picker */
415
  visibleYearsRange?: {
416
    startYear: number;
417
    endYear: number;
418
  };
419
}
420
```
421

422
**Custom Header Example:**
423

424
```typescript
425
function CustomHeader({
426
  date,
427
  changeYear,
428
  changeMonth,
429
  decreaseMonth,
430
  increaseMonth,
431
  prevMonthButtonDisabled,
432
  nextMonthButtonDisabled,
433
}: ReactDatePickerCustomHeaderProps) {
434
  return (
435
    <div className="custom-header">
436
      <button onClick={decreaseMonth} disabled={prevMonthButtonDisabled}>
437
        {"<"}
438
      </button>
439
      <select
440
        value={date.getFullYear()}
441
        onChange={({ target: { value } }) => changeYear(parseInt(value))}
442
      >
443
        {Array.from({ length: 10 }, (_, i) => (
444
          <option key={i} value={date.getFullYear() - 5 + i}>
445
            {date.getFullYear() - 5 + i}
446
          </option>
447
        ))}
448
      </select>
449
      <select
450
        value={date.getMonth()}
451
        onChange={({ target: { value } }) => changeMonth(parseInt(value))}
452
      >
453
        {Array.from({ length: 12 }, (_, i) => (
454
          <option key={i} value={i}>
455
            {new Date(0, i).toLocaleDateString("en", { month: "long" })}
456
          </option>
457
        ))}
458
      </select>
459
      <button onClick={increaseMonth} disabled={nextMonthButtonDisabled}>
460
        {">"}
461
      </button>
462
    </div>
463
  );
464
}
465

466
// Use with DatePicker
467
function DatePickerWithCustomHeader() {
468
  const [date, setDate] = useState<Date | null>(new Date());
469
  
470
  return (
471
    <DatePicker
472
      selected={date}
473
      onChange={setDate}
474
      renderCustomHeader={CustomHeader}
475
    />
476
  );
477
}
478
```