0
# React Day Picker
1
2
React Day Picker is a comprehensive React component library for creating customizable date pickers, calendars, and date inputs. It provides extensive customization options through props, supports multiple selection modes (single days, multiple days, date ranges, and custom selections), and offers internationalization capabilities with support for various calendar systems including ISO 8601, Persian, and broadcast calendars.
3
4
## Package Information
5
6
- **Package Name**: react-day-picker
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-day-picker`
10
11
## Core Imports
12
13
```typescript
14
import { DayPicker } from "react-day-picker";
15
```
16
17
For specific selection modes:
18
19
```typescript
20
import { DayPicker, type DateRange, type SelectHandler } from "react-day-picker";
21
```
22
23
For CommonJS:
24
25
```javascript
26
const { DayPicker } = require("react-day-picker");
27
```
28
29
## Basic Usage
30
31
```typescript
32
import React, { useState } from "react";
33
import { DayPicker, type DateRange } from "react-day-picker";
34
import "react-day-picker/style.css";
35
36
function MyDatePicker() {
37
const [selected, setSelected] = useState<Date>();
38
39
return (
40
<DayPicker
41
mode="single"
42
selected={selected}
43
onSelect={setSelected}
44
/>
45
);
46
}
47
48
// Range selection example
49
function MyRangePicker() {
50
const [range, setRange] = useState<DateRange | undefined>();
51
52
return (
53
<DayPicker
54
mode="range"
55
defaultMonth={new Date()}
56
selected={range}
57
onSelect={setRange}
58
/>
59
);
60
}
61
```
62
63
## Architecture
64
65
React Day Picker is built around several key components:
66
67
- **Main Component**: `DayPicker` - The primary React component with extensive prop configuration
68
- **Selection System**: Type-safe selection modes for single dates, multiple dates, and date ranges
69
- **Customization Layer**: Complete component override system, custom formatters, and styling options
70
- **Internationalization**: Built-in locale support with date-fns integration and custom calendar systems
71
- **Accessibility**: WCAG 2.1 AA compliant with full keyboard navigation and screen reader support
72
- **Date Management**: Custom `DateLib` class wrapping date-fns with locale and timezone support
73
74
## Capabilities
75
76
### Main Component
77
78
The core `DayPicker` React component with comprehensive configuration options for rendering customizable calendars.
79
80
```typescript { .api }
81
function DayPicker(props: DayPickerProps): React.ReactElement;
82
83
type DayPickerProps = PropsBase & (
84
| PropsSingle
85
| PropsSingleRequired
86
| PropsMulti
87
| PropsMultiRequired
88
| PropsRange
89
| PropsRangeRequired
90
| { mode?: undefined; required?: undefined }
91
);
92
```
93
94
[Main Component Configuration](./main-component.md)
95
96
### Selection Modes
97
98
Type-safe selection system supporting single date, multiple dates, and date range selection with controlled and uncontrolled modes.
99
100
```typescript { .api }
101
type Mode = "single" | "multiple" | "range";
102
103
type SelectedValue<T extends DayPickerProps> =
104
T["mode"] extends "single" ? Date | undefined :
105
T["mode"] extends "multiple" ? Date[] | undefined :
106
T["mode"] extends "range" ? DateRange | undefined :
107
never;
108
109
type SelectHandler<T extends DayPickerProps> = (
110
value: SelectedValue<T>,
111
triggerDate: Date,
112
modifiers: Modifiers,
113
e: React.MouseEvent
114
) => void;
115
```
116
117
[Selection System](./selection.md)
118
119
### Customization System
120
121
Complete component override system allowing replacement of any UI element with custom React components.
122
123
```typescript { .api }
124
interface CustomComponents {
125
Root?: React.ComponentType<RootProps>;
126
Month?: React.ComponentType<MonthProps>;
127
Day?: React.ComponentType<DayProps>;
128
DayButton?: React.ComponentType<DayButtonProps>;
129
// ... 20+ customizable components
130
}
131
132
interface ClassNames {
133
[UI.Root]: string;
134
[UI.Month]: string;
135
[UI.Day]: string;
136
// ... corresponding class names for all UI elements
137
}
138
```
139
140
[Customization Options](./customization.md)
141
142
### Internationalization
143
144
Built-in support for multiple locales, calendar systems, and formatting options with date-fns integration.
145
146
```typescript { .api }
147
interface Locale {
148
code: string;
149
formatDistance?: Function;
150
formatRelative?: Function;
151
localize?: Function;
152
formatLong?: Function;
153
match?: Function;
154
options?: {
155
weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
156
firstWeekContainsDate?: 1 | 2 | 3 | 4 | 5 | 6 | 7;
157
};
158
}
159
160
class DateLib {
161
constructor(options: DateLibOptions, overrides?: Partial<DateLib>);
162
// 50+ date utility methods
163
}
164
```
165
166
[Internationalization](./internationalization.md)
167
168
### Date Range Utilities
169
170
Utility functions for working with date ranges, intervals, and date matching patterns.
171
172
```typescript { .api }
173
interface DateRange {
174
from: Date | undefined;
175
to: Date | undefined;
176
}
177
178
function addToRange(
179
date: Date,
180
range: DateRange | undefined,
181
options?: { min?: number; max?: number }
182
): DateRange | undefined;
183
184
function rangeIncludesDate(
185
range: DateRange,
186
date: Date,
187
excludeEnds?: boolean,
188
dateLib?: DateLib
189
): boolean;
190
```
191
192
[Date Utilities](./date-utilities.md)
193
194
### Styling System
195
196
Comprehensive styling system supporting CSS classes, inline styles, and CSS modules with modifier-based styling.
197
198
```typescript { .api }
199
interface Styles {
200
[UI.Root]?: React.CSSProperties;
201
[UI.Month]?: React.CSSProperties;
202
[UI.Day]?: React.CSSProperties;
203
// ... styles for all UI elements
204
}
205
206
interface ModifiersStyles {
207
[modifier: string]: React.CSSProperties;
208
}
209
```
210
211
[Styling System](./styling.md)
212
213
## Types
214
215
### Core Types
216
217
```typescript { .api }
218
interface DayPickerProps extends PropsBase {
219
mode?: Mode;
220
required?: boolean;
221
}
222
223
interface PropsBase {
224
className?: string;
225
classNames?: Partial<ClassNames>;
226
style?: React.CSSProperties;
227
styles?: Partial<Styles>;
228
id?: string;
229
// ... 50+ configuration props
230
}
231
232
interface Modifiers {
233
[modifier: string]: boolean;
234
}
235
236
type Matcher =
237
| boolean
238
| ((date: Date) => boolean)
239
| Date
240
| Date[]
241
| DateRange
242
| DateInterval
243
| DayOfWeek;
244
```
245
246
### Selection Props Types
247
248
```typescript { .api }
249
interface PropsSingle {
250
mode: "single";
251
selected?: Date;
252
onSelect?: (date: Date | undefined, triggerDate: Date, modifiers: Modifiers, e: React.MouseEvent) => void;
253
}
254
255
interface PropsRange {
256
mode: "range";
257
selected?: DateRange;
258
onSelect?: (range: DateRange | undefined, triggerDate: Date, modifiers: Modifiers, e: React.MouseEvent) => void;
259
}
260
261
interface PropsMulti {
262
mode: "multiple";
263
selected?: Date[];
264
onSelect?: (dates: Date[] | undefined, triggerDate: Date, modifiers: Modifiers, e: React.MouseEvent) => void;
265
}
266
```