0
# React Dates
1

2
React Dates is a comprehensive, responsive, and accessible date picker library built with React. It provides three main date selection components with extensive customization options, accessibility features, and internationalization support through Moment.js integration.
3

4
## Package Information
5

6
- **Package Name**: react-dates
7
- **Package Type**: npm
8
- **Language**: JavaScript/React
9
- **Installation**: `npm install react-dates`
10

11
## Core Imports
12

13
```javascript
14
import {
15
  DateRangePicker,
16
  SingleDatePicker,
17
  DayPickerRangeController
18
} from "react-dates";
19
```
20

21
For CommonJS:
22

23
```javascript
24
const {
25
  DateRangePicker,
26
  SingleDatePicker,
27
  DayPickerRangeController
28
} = require("react-dates");
29
```
30

31
## Basic Usage
32

33
```jsx
34
import React, { useState } from "react";
35
import {
36
  DateRangePicker,
37
  SingleDatePicker
38
} from "react-dates";
39
import moment from "moment";
40

41
// Required: Initialize CSS interface
42
import "react-dates/initialize";
43
// Required: Import CSS styles
44
import "react-dates/lib/css/_datepicker.css";
45

46
// Date Range Picker
47
function MyDateRangePicker() {
48
  const [startDate, setStartDate] = useState(null);
49
  const [endDate, setEndDate] = useState(null);
50
  const [focusedInput, setFocusedInput] = useState(null);
51

52
  return (
53
    <DateRangePicker
54
      startDate={startDate}
55
      startDateId="your_unique_start_date_id"
56
      endDate={endDate}
57
      endDateId="your_unique_end_date_id"
58
      onDatesChange={({ startDate, endDate }) => {
59
        setStartDate(startDate);
60
        setEndDate(endDate);
61
      }}
62
      focusedInput={focusedInput}
63
      onFocusChange={setFocusedInput}
64
    />
65
  );
66
}
67

68
// Single Date Picker
69
function MySingleDatePicker() {
70
  const [date, setDate] = useState(null);
71
  const [focused, setFocused] = useState(false);
72

73
  return (
74
    <SingleDatePicker
75
      date={date}
76
      onDateChange={setDate}
77
      focused={focused}
78
      onFocusChange={({ focused }) => setFocused(focused)}
79
      id="your_unique_id"
80
    />
81
  );
82
}
83
```
84

85
## Architecture
86

87
React Dates is built around several key components:
88

89
- **Main Pickers**: High-level date picker components with input fields and calendar displays
90
- **Controller Components**: Headless calendar components for custom implementations
91
- **Input Components**: Standalone input field components for custom layouts
92
- **Calendar Components**: Low-level calendar rendering components
93
- **Utility Functions**: Date comparison and conversion helpers
94
- **Shape Definitions**: PropTypes validation schemas
95

96
The library emphasizes accessibility with screen reader support, keyboard navigation, and ARIA labeling. It supports responsive design with multiple orientations, portal rendering, and mobile-optimized layouts.
97

98
## Capabilities
99

100
### Main Date Pickers
101

102
Complete date picker components with input fields and calendar dropdowns. Perfect for forms and user interfaces requiring date selection.
103

104
```jsx { .api }
105
// Date range selection component
106
function DateRangePicker(props: DateRangePickerProps): ReactElement;
107

108
// Single date selection component  
109
function SingleDatePicker(props: SingleDatePickerProps): ReactElement;
110
```
111

112
[Main Date Pickers](./main-pickers.md)
113

114
### Calendar Controllers
115

116
Headless calendar components without input fields, ideal for custom implementations and embedded calendars.
117

118
```jsx { .api }
119
// Calendar-only date range controller
120
function DayPickerRangeController(props: DayPickerRangeControllerProps): ReactElement;
121

122
// Calendar-only single date controller
123
function DayPickerSingleDateController(props: DayPickerSingleDateControllerProps): ReactElement;
124
```
125

126
[Calendar Controllers](./calendar-controllers.md)
127

128
### Input Components
129

130
Standalone input field components for custom layouts and advanced use cases.
131

132
```jsx { .api }
133
// Date range input fields
134
function DateRangePickerInput(props: DateRangePickerInputProps): ReactElement;
135
function DateRangePickerInputController(props: DateRangePickerInputControllerProps): ReactElement;
136

137
// Single date input field
138
function SingleDatePickerInput(props: SingleDatePickerInputProps): ReactElement;
139
```
140

141
[Input Components](./input-components.md)
142

143
### Calendar Components
144

145
Low-level calendar rendering components for building custom date picker interfaces.
146

147
```jsx { .api }
148
// Complete calendar component with navigation
149
function DayPicker(props: DayPickerProps): ReactElement;
150

151
// Month grid layout for multiple months
152
function CalendarMonthGrid(props: CalendarMonthGridProps): ReactElement;
153

154
// Individual month view
155
function CalendarMonth(props: CalendarMonthProps): ReactElement;
156

157
// Individual day cell
158
function CalendarDay(props: CalendarDayProps): ReactElement;
159
```
160

161
[Calendar Components](./calendar-components.md)
162

163
### Utility Functions
164

165
Date comparison and conversion utilities for working with Moment.js objects.
166

167
```javascript { .api }
168
// Date comparison functions
169
function isSameDay(a: moment.Moment, b: moment.Moment): boolean;
170
function isInclusivelyAfterDay(a: moment.Moment, b: moment.Moment): boolean;
171
function isInclusivelyBeforeDay(a: moment.Moment, b: moment.Moment): boolean;
172
function isNextDay(a: moment.Moment, b: moment.Moment): boolean;
173

174
// Date conversion functions
175
function toISODateString(date: moment.Moment | string, currentFormat?: string): string;
176
function toLocalizedDateString(date: moment.Moment | string, currentFormat?: string): string;
177
function toMomentObject(dateString: string, customFormat?: string): moment.Moment | null;
178
```
179

180
[Utility Functions](./utilities.md)
181

182
## Common Constants
183

184
React Dates exports several constants for configuration:
185

186
```javascript { .api }
187
// Import constants from react-dates
188
import {
189
  START_DATE,
190
  END_DATE,
191
  HORIZONTAL_ORIENTATION,
192
  VERTICAL_ORIENTATION,
193
  VERTICAL_SCROLLABLE,
194
  ICON_BEFORE_POSITION,
195
  ICON_AFTER_POSITION,
196
  ANCHOR_LEFT,
197
  ANCHOR_RIGHT,
198
  OPEN_DOWN,
199
  OPEN_UP,
200
  NAV_POSITION_TOP,
201
  NAV_POSITION_BOTTOM,
202
  INFO_POSITION_TOP,
203
  INFO_POSITION_BOTTOM,
204
  INFO_POSITION_BEFORE,
205
  INFO_POSITION_AFTER,
206
  DISPLAY_FORMAT,
207
  ISO_FORMAT,
208
  DAY_SIZE,
209
  WEEKDAYS
210
} from "react-dates";
211

212
// Focus states for date range picker
213
START_DATE: "startDate";
214
END_DATE: "endDate";
215

216
// Orientation options
217
HORIZONTAL_ORIENTATION: "horizontal";
218
VERTICAL_ORIENTATION: "vertical";
219
VERTICAL_SCROLLABLE: "verticalScrollable";
220

221
// Icon positions
222
ICON_BEFORE_POSITION: "before";
223
ICON_AFTER_POSITION: "after";
224

225
// Anchor directions
226
ANCHOR_LEFT: "left";
227
ANCHOR_RIGHT: "right";
228

229
// Open directions
230
OPEN_DOWN: "down";
231
OPEN_UP: "up";
232

233
// Navigation positions
234
NAV_POSITION_TOP: "navPositionTop";
235
NAV_POSITION_BOTTOM: "navPositionBottom";
236

237
// Info panel positions
238
INFO_POSITION_TOP: "top";
239
INFO_POSITION_BOTTOM: "bottom";
240
INFO_POSITION_BEFORE: "before";
241
INFO_POSITION_AFTER: "after";
242

243
// Date formats
244
DISPLAY_FORMAT: "L";
245
ISO_FORMAT: "YYYY-MM-DD";
246

247
// Layout constants
248
DAY_SIZE: 39;
249
WEEKDAYS: [0, 1, 2, 3, 4, 5, 6];
250

251
// Validation function types
252
type DayValidationFunction = (day: moment.Moment) => boolean;
253

254
// Date change handlers
255
type DateRangeChangeHandler = ({ startDate, endDate }: {
256
  startDate: moment.Moment | null;
257
  endDate: moment.Moment | null;
258
}) => void;
259

260
type SingleDateChangeHandler = (date: moment.Moment | null) => void;
261

262
// Focus change handlers
263
type FocusChangeHandler = (focusedInput: 'startDate' | 'endDate' | null) => void;
264
type SingleFocusChangeHandler = ({ focused }: { focused: boolean }) => void;
265
```
266

267
## Accessibility Features
268

269
- **Screen Reader Support**: Complete ARIA labeling and screen reader announcements
270
- **Keyboard Navigation**: Arrow keys, Tab, Enter, Escape key support
271
- **Focus Management**: Proper focus indicators and logical tab order
272
- **Customizable Labels**: Override all text for localization and accessibility needs
273

274
## Required Initialization
275

276
React Dates requires CSS interface initialization before use:
277

278
```javascript
279
// Import and run initialization (required)
280
import "react-dates/initialize";
281

282
// Or manually initialize
283
import { registerCSSInterfaceWithDefaultTheme } from "react-dates/lib/initialize";
284
registerCSSInterfaceWithDefaultTheme();
285
```
286

287
## CSS Import
288

289
You must also import the required CSS styles:
290

291
```css
292
@import '~react-dates/lib/css/_datepicker.css';
293
```
294

295
Or include it in your HTML:
296

297
```html
298
<link rel="stylesheet" type="text/css" href="./node_modules/react-dates/lib/css/_datepicker.css" />
299
```
300

301
## Common Validation Patterns
302

303
```javascript
304
// Block past dates
305
const isOutsideRange = (day) => moment().diff(day) > 0;
306

307
// Block specific dates
308
const isDayBlocked = (day) => {
309
  const blockedDates = ['2023-12-25', '2023-01-01'];
310
  return blockedDates.includes(day.format('YYYY-MM-DD'));
311
};
312

313
// Highlight special dates
314
const isDayHighlighted = (day) => {
315
  const holidays = ['2023-12-25', '2023-07-04'];
316
  return holidays.includes(day.format('YYYY-MM-DD'));
317
};
318
```
319

320
## Error Handling
321

322
The library handles validation through callback functions rather than throwing exceptions. Invalid states are communicated through:
323

324
- Blocked dates (non-selectable)
325
- Outside range dates (visually distinguished)
326
- Custom validation feedback through `isDayBlocked` and `isOutsideRange` functions