0
# React DatePicker
1

2
React DatePicker is a comprehensive React component library that provides a powerful and customizable date picker interface. It supports single date selection, date ranges, multiple date selection, time picking, extensive localization, accessibility features, and advanced filtering options through an intuitive React component API.
3

4
## Package Information
5

6
- **Package Name**: react-datepicker
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-datepicker`
10

11
## Core Imports
12

13
```typescript
14
import DatePicker from "react-datepicker";
15
import { registerLocale, setDefaultLocale, getDefaultLocale, CalendarContainer } from "react-datepicker";
16
import type { ReactDatePickerCustomHeaderProps } from "react-datepicker";
17
import "react-datepicker/dist/react-datepicker.css";
18
```
19

20
For CommonJS:
21

22
```javascript
23
const DatePicker = require("react-datepicker").default;
24
const { registerLocale, setDefaultLocale, getDefaultLocale, CalendarContainer } = require("react-datepicker");
25
require("react-datepicker/dist/react-datepicker.css");
26
```
27

28
## Basic Usage
29

30
```typescript
31
import React, { useState } from "react";
32
import DatePicker from "react-datepicker";
33
import "react-datepicker/dist/react-datepicker.css";
34

35
function MyDatePicker() {
36
  const [startDate, setStartDate] = useState<Date | null>(new Date());
37

38
  return (
39
    <DatePicker
40
      selected={startDate}
41
      onChange={(date) => setStartDate(date)}
42
      dateFormat="MM/dd/yyyy"
43
      placeholderText="Select a date"
44
    />
45
  );
46
}
47

48
// Date range selection
49
function DateRangePicker() {
50
  const [startDate, setStartDate] = useState<Date | null>(null);
51
  const [endDate, setEndDate] = useState<Date | null>(null);
52

53
  return (
54
    <DatePicker
55
      selected={startDate}
56
      onChange={(dates: [Date | null, Date | null]) => {
57
        const [start, end] = dates;
58
        setStartDate(start);
59
        setEndDate(end);
60
      }}
61
      startDate={startDate}
62
      endDate={endDate}
63
      selectsRange
64
      inline
65
    />
66
  );
67
}
68
```
69

70
## Architecture
71

72
React DatePicker is built around several key components:
73

74
- **DatePicker Component**: Main React component providing the complete date picker interface
75
- **Calendar System**: Internal calendar rendering with month/year navigation and day selection
76
- **Date Utilities**: Comprehensive date manipulation and formatting functions built on date-fns
77
- **Localization Engine**: Full internationalization support with date-fns locale integration
78
- **Accessibility Framework**: Complete ARIA support and keyboard navigation
79
- **Theming System**: CSS-based styling with multiple theme options and customization points
80

81
## Capabilities
82

83
### Core Date Picker Functionality
84

85
The main DatePicker component with support for single dates, date ranges, multiple selection, and extensive customization options.
86

87
```typescript { .api }
88
import DatePicker from "react-datepicker";
89

90
interface DatePickerProps {
91
  // Core date selection
92
  selected?: Date | null;
93
  onChange?: (date: Date | null, event?: React.SyntheticEvent) => void;
94
  
95
  // Date range selection
96
  selectsRange?: boolean;
97
  startDate?: Date | null;
98
  endDate?: Date | null;
99
  
100
  // Multiple date selection
101
  selectsMultiple?: boolean;
102
  selectedDates?: Date[];
103
  
104
  // Display options
105
  inline?: boolean;
106
  dateFormat?: string | string[];
107
  placeholderText?: string;
108
  
109
  // Constraints
110
  minDate?: Date;
111
  maxDate?: Date;
112
  excludeDates?: Date[];
113
  includeDates?: Date[];
114
  
115
  // Customization
116
  customInput?: React.ReactElement;
117
  calendarClassName?: string;
118
  wrapperClassName?: string;
119
}
120

121
function DatePicker(props: DatePickerProps): React.ReactElement;
122
```
123

124
[Core Functionality](./core-functionality.md)
125

126
### Date Utilities
127

128
Comprehensive date manipulation, formatting, and calculation functions for working with dates in JavaScript applications.
129

130
```typescript { .api }
131
// Date creation and parsing
132
function newDate(value?: string | Date | number | null): Date;
133
function parseDate(value: string, format: string | string[], locale?: Locale, strictParsing?: boolean): Date | null;
134

135
// Date formatting
136
function formatDate(date: Date, format: string, locale?: Locale): string;
137
function safeDateFormat(date: Date | null, options: {dateFormat: string | string[], locale?: Locale}): string;
138

139
// Date comparisons
140
function isBefore(date: Date, dateToCompare: Date): boolean;
141
function isAfter(date: Date, dateToCompare: Date): boolean;
142
function isSameDay(date: Date, dateToCompare: Date): boolean;
143
```
144

145
[Date Utilities](./date-utilities.md)
146

147
### Localization and Internationalization
148

149
Complete internationalization support with date-fns locale integration for global applications.
150

151
```typescript { .api }
152
type Locale = string | LocaleObject;
153

154
function registerLocale(localeName: string, localeData: LocaleObject): void;
155
function setDefaultLocale(locale: string): void;
156
function getDefaultLocale(): string;
157
```
158

159
[Localization](./localization.md)
160

161
### Calendar Container
162

163
Customizable container component for advanced calendar layout and accessibility features.
164

165
```typescript { .api }
166
interface CalendarContainerProps extends React.HTMLAttributes<HTMLDivElement> {
167
  showTimeSelectOnly?: boolean;
168
  showTime?: boolean;
169
}
170

171
function CalendarContainer(props: CalendarContainerProps): React.ReactElement;
172
```
173

174
## Types
175

176
```typescript { .api }
177
// Core types
178
type Locale = string | LocaleObject;
179

180
interface LocaleObject {
181
  options?: LocaleOptions;
182
  formatLong?: FormatLongObject;
183
  localize?: LocalizeObject;
184
  match?: MatchObject;
185
}
186

187
interface DatePickerProps {
188
  // Main date selection props
189
  selected?: Date | null;
190
  onChange?: (date: Date | null | [Date | null, Date | null] | Date[], event?: React.SyntheticEvent) => void;
191
  
192
  // Selection modes
193
  selectsRange?: boolean;
194
  selectsMultiple?: boolean;
195
  
196
  // Date constraints
197
  minDate?: Date;
198
  maxDate?: Date;
199
  excludeDates?: Date[];
200
  includeDates?: Date[];
201
  excludeDateIntervals?: Array<{start: Date, end: Date}>;
202
  includeDateIntervals?: Array<{start: Date, end: Date}>;
203
  
204
  // Display and formatting
205
  dateFormat?: string | string[];
206
  locale?: Locale;
207
  inline?: boolean;
208
  
209
  // Time selection
210
  showTimeSelect?: boolean;
211
  showTimeSelectOnly?: boolean;
212
  timeFormat?: string;
213
  timeIntervals?: number;
214
  minTime?: Date;
215
  maxTime?: Date;
216
  
217
  // Calendar features
218
  showMonthDropdown?: boolean;
219
  showYearDropdown?: boolean;
220
  showWeekNumbers?: boolean;
221
  highlightDates?: Array<Date | {date: Date, className: string}>;
222
  
223
  // Accessibility
224
  ariaLabelledBy?: string;
225
  ariaDescribedBy?: string;
226
  
227
  // Events
228
  onFocus?: (event: React.FocusEvent) => void;
229
  onBlur?: (event: React.FocusEvent) => void;
230
  onCalendarOpen?: () => void;
231
  onCalendarClose?: () => void;
232
  
233
  // Customization
234
  customInput?: React.ReactElement;
235
  customInputRef?: string;
236
  className?: string;
237
  calendarClassName?: string;
238
  popperClassName?: string;
239
  
240
  // Portal and positioning
241
  withPortal?: boolean;
242
  portalId?: string;
243
  popperPlacement?: string;
244
  
245
  // Form integration
246
  id?: string;
247
  name?: string;
248
  required?: boolean;
249
  disabled?: boolean;
250
  readOnly?: boolean;
251
  autoComplete?: string;
252
  
253
  // Advanced features
254
  filterDate?: (date: Date) => boolean;
255
  filterTime?: (time: Date) => boolean;
256
  shouldCloseOnSelect?: boolean;
257
  preventOpenOnFocus?: boolean;
258
}
259

260
// Date utility types
261
enum KeyType {
262
  ArrowUp = "ArrowUp",
263
  ArrowDown = "ArrowDown",
264
  ArrowLeft = "ArrowLeft",
265
  ArrowRight = "ArrowRight",
266
  PageUp = "PageUp",
267
  PageDown = "PageDown",
268
  Home = "Home",
269
  End = "End",
270
  Enter = "Enter",
271
  Space = " ",
272
  Tab = "Tab",
273
  Escape = "Escape"
274
}
275

276
interface HighlightDate {
277
  date: Date;
278
  className?: string;
279
}
280

281
interface Holiday {
282
  date: string;
283
  holidayName: string;
284
}
285

286
// Custom header interface
287
interface ReactDatePickerCustomHeaderProps {
288
  date: Date;
289
  customHeaderCount: number;
290
  monthDate: Date;
291
  changeMonth: (month: number) => void;
292
  changeYear: (year: number) => void;
293
  decreaseMonth: () => void;
294
  increaseMonth: () => void;
295
  decreaseYear: () => void;
296
  increaseYear: () => void;
297
  prevMonthButtonDisabled: boolean;
298
  nextMonthButtonDisabled: boolean;
299
  prevYearButtonDisabled: boolean;
300
  nextYearButtonDisabled: boolean;
301
  visibleYearsRange?: {
302
    startYear: number;
303
    endYear: number;
304
  };
305
}
306
```
307

308
## Constants
309

310
```typescript { .api }
311
const DEFAULT_YEAR_ITEM_NUMBER: number = 12;
312
const DATE_RANGE_SEPARATOR: string = " - ";
313
const OUTSIDE_CLICK_IGNORE_CLASS: string = "react-datepicker-ignore-onclickoutside";
314
```