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
```