0
# MUI X Date Pickers
1

2
MUI X Date Pickers provides comprehensive React date and time picker components that integrate seamlessly with Material-UI design system. The library offers DatePicker, TimePicker, and DateTimePicker components with support for multiple date libraries including date-fns, Day.js, Luxon, and Moment.js, featuring advanced functionality such as localization support, keyboard navigation, accessibility compliance, and mobile-responsive design.
3

4
## Package Information
5

6
- **Package Name**: @mui/x-date-pickers
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @mui/x-date-pickers @mui/material @emotion/react @emotion/styled`
10

11
## Core Imports
12

13
ESM imports:
14

15
```typescript
16
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
17
import { DatePicker } from '@mui/x-date-pickers/DatePicker';
18
import { TimePicker } from '@mui/x-date-pickers/TimePicker';
19
import { DateTimePicker } from '@mui/x-date-pickers/DateTimePicker';
20
import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
21
import { PickerDay2 } from '@mui/x-date-pickers/PickerDay2';
22
import { DayCalendarSkeleton } from '@mui/x-date-pickers/DayCalendarSkeleton';
23
```
24

25
Barrel imports:
26

27
```typescript
28
import {
29
  LocalizationProvider,
30
  DatePicker,
31
  TimePicker, 
32
  DateTimePicker,
33
  AdapterDayjs,
34
  PickerDay2,
35
  DayCalendarSkeleton
36
} from '@mui/x-date-pickers';
37
```
38

39
## Basic Usage
40

41
```typescript
42
import * as React from 'react';
43
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
44
import { DatePicker } from '@mui/x-date-pickers/DatePicker';
45
import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
46
import dayjs, { Dayjs } from 'dayjs';
47

48
function App() {
49
  const [value, setValue] = React.useState<Dayjs | null>(dayjs('2022-04-17'));
50

51
  return (
52
    <LocalizationProvider dateAdapter={AdapterDayjs}>
53
      <DatePicker 
54
        label="Basic date picker"
55
        value={value}
56
        onChange={(newValue) => setValue(newValue)}
57
      />
58
    </LocalizationProvider>
59
  );
60
}
61
```
62

63
## Architecture
64

65
MUI X Date Pickers is built around several key architectural patterns:
66

67
- **Adapter System**: Pluggable date library adapters (date-fns, dayjs, luxon, moment) for flexible date manipulation
68
- **Localization Provider**: Centralized localization and date adapter configuration
69
- **Responsive Design**: Automatic desktop/mobile optimizations with separate component variants
70
- **Field Components**: Standalone input fields that can be used independently of pickers
71
- **Slot Architecture**: Extensible component customization through MUI's slot system
72
- **Validation System**: Comprehensive date/time validation with custom rule support
73
- **View System**: Modular view components (calendar, clock) that can be composed into different picker types
74

75
## Capabilities
76

77
### Date Pickers
78

79
Core date selection components with calendar interface, available in responsive variants for desktop, mobile, and always-visible static modes.
80

81
```typescript { .api }
82
function DatePicker<TDate>(props: DatePickerProps<TDate>): JSX.Element;
83
function DesktopDatePicker<TDate>(props: DesktopDatePickerProps<TDate>): JSX.Element;
84
function MobileDatePicker<TDate>(props: MobileDatePickerProps<TDate>): JSX.Element;
85
function StaticDatePicker<TDate>(props: StaticDatePickerProps<TDate>): JSX.Element;
86

87
interface DatePickerProps<TDate> {
88
  value?: TDate | null;
89
  onChange?: (value: TDate | null, context: PickerChangeContext) => void;
90
  label?: React.ReactNode;
91
  disabled?: boolean;
92
  readOnly?: boolean;
93
  disableFuture?: boolean;
94
  disablePast?: boolean;
95
  minDate?: TDate;
96
  maxDate?: TDate;
97
  shouldDisableDate?: (day: TDate) => boolean;
98
  views?: readonly DateView[];
99
  openTo?: DateView;
100
  format?: string;
101
  slotProps?: DatePickerSlotProps<TDate>;
102
  slots?: DatePickerSlots<TDate>;
103
}
104

105
type DateView = 'year' | 'month' | 'day';
106
```
107

108
[Date Pickers](./date-pickers.md)
109

110
### Time Pickers
111

112
Time selection components with analog clock and digital time interfaces, supporting hours, minutes, and seconds selection with customizable time steps.
113

114
```typescript { .api }
115
function TimePicker<TDate>(props: TimePickerProps<TDate>): JSX.Element;
116
function DesktopTimePicker<TDate>(props: DesktopTimePickerProps<TDate>): JSX.Element;
117
function MobileTimePicker<TDate>(props: MobileTimePickerProps<TDate>): JSX.Element;
118
function StaticTimePicker<TDate>(props: StaticTimePickerProps<TDate>): JSX.Element;
119

120
interface TimePickerProps<TDate> {
121
  value?: TDate | null;
122
  onChange?: (value: TDate | null, context: PickerChangeContext) => void;
123
  label?: React.ReactNode;
124
  disabled?: boolean;
125
  readOnly?: boolean;
126
  minTime?: TDate;
127
  maxTime?: TDate;
128
  shouldDisableTime?: (value: TDate, view: TimeView) => boolean;
129
  views?: readonly TimeView[];
130
  openTo?: TimeView;
131
  format?: string;
132
  timeSteps?: TimeStepOptions;
133
  slotProps?: TimePickerSlotProps<TDate>;
134
  slots?: TimePickerSlots<TDate>;
135
}
136

137
type TimeView = 'hours' | 'minutes' | 'seconds';
138

139
interface TimeStepOptions {
140
  hours?: number;
141
  minutes?: number;
142
  seconds?: number;
143
}
144
```
145

146
[Time Pickers](./time-pickers.md)
147

148
### Date-Time Pickers
149

150
Combined date and time selection with tabbed interface for switching between date and time views, providing comprehensive date-time input functionality.
151

152
```typescript { .api }
153
function DateTimePicker<TDate>(props: DateTimePickerProps<TDate>): JSX.Element;
154
function DesktopDateTimePicker<TDate>(props: DesktopDateTimePickerProps<TDate>): JSX.Element;
155
function MobileDateTimePicker<TDate>(props: MobileDateTimePickerProps<TDate>): JSX.Element;
156
function StaticDateTimePicker<TDate>(props: StaticDateTimePickerProps<TDate>): JSX.Element;
157

158
interface DateTimePickerProps<TDate> {
159
  value?: TDate | null;
160
  onChange?: (value: TDate | null, context: PickerChangeContext) => void;
161
  label?: React.ReactNode;
162
  disabled?: boolean;
163
  readOnly?: boolean;
164
  disableFuture?: boolean;
165
  disablePast?: boolean;
166
  minDateTime?: TDate;
167
  maxDateTime?: TDate;
168
  shouldDisableDate?: (day: TDate) => boolean;
169
  shouldDisableTime?: (value: TDate, view: TimeView) => boolean;
170
  views?: readonly DateOrTimeView[];
171
  openTo?: DateOrTimeView;
172
  format?: string;
173
  timeSteps?: TimeStepOptions;
174
  slotProps?: DateTimePickerSlotProps<TDate>;
175
  slots?: DateTimePickerSlots<TDate>;
176
}
177

178
type DateOrTimeView = DateView | TimeView;
179
```
180

181
[Date-Time Pickers](./datetime-pickers.md)
182

183
### Field Components
184

185
Standalone input field components for date, time, and date-time values with sectioned editing, keyboard navigation, and validation support.
186

187
```typescript { .api }
188
function DateField<TDate>(props: DateFieldProps<TDate>): JSX.Element;
189
function TimeField<TDate>(props: TimeFieldProps<TDate>): JSX.Element;
190
function DateTimeField<TDate>(props: DateTimeFieldProps<TDate>): JSX.Element;
191

192
interface DateFieldProps<TDate> {
193
  value?: TDate | null;
194
  onChange?: (value: TDate | null, context: FieldChangeContext<TDate>) => void;
195
  format?: string;
196
  disabled?: boolean;
197
  readOnly?: boolean;
198
  shouldRespectLeadingZeros?: boolean;
199
  ref?: React.Ref<FieldRef<TDate>>;
200
}
201

202
interface FieldRef<TDate> {
203
  getSections(): FieldSection[];
204
  getActiveSectionIndex(): number | null;
205
  setSelectedSections(selectedSections: FieldSelectedSections): void;
206
  focusField(newSelectedSection?: number | FieldSectionType): void;
207
  isFieldFocused(): boolean;
208
}
209
```
210

211
[Field Components](./field-components.md)
212

213
### Calendar and Clock Components
214

215
Standalone calendar and clock view components for building custom date/time selection interfaces.
216

217
```typescript { .api }
218
function DateCalendar<TDate>(props: DateCalendarProps<TDate>): JSX.Element;
219
function MonthCalendar<TDate>(props: MonthCalendarProps<TDate>): JSX.Element;
220
function YearCalendar<TDate>(props: YearCalendarProps<TDate>): JSX.Element;
221
function TimeClock<TDate>(props: TimeClockProps<TDate>): JSX.Element;
222
function DigitalClock<TDate>(props: DigitalClockProps<TDate>): JSX.Element;
223
function MultiSectionDigitalClock<TDate>(props: MultiSectionDigitalClockProps<TDate>): JSX.Element;
224
```
225

226
[Calendar and Clock Components](./calendar-clock-components.md)
227

228
### Adapters and Localization
229

230
Date library adapters and localization provider for configuring date manipulation and internationalization across all picker components.
231

232
```typescript { .api }
233
function LocalizationProvider<TDate>(props: LocalizationProviderProps<TDate>): JSX.Element;
234

235
interface LocalizationProviderProps<TDate> {
236
  dateAdapter: MuiPickersAdapter<TDate>;
237
  adapterLocale?: any;
238
  children: React.ReactNode;
239
  localeText?: Partial<PickersLocaleText<TDate>>;
240
}
241

242
// Date Library Adapters
243
class AdapterDateFns implements MuiPickersAdapter<Date>;
244
class AdapterDayjs implements MuiPickersAdapter<dayjs.Dayjs>;
245
class AdapterLuxon implements MuiPickersAdapter<luxon.DateTime>;
246
class AdapterMoment implements MuiPickersAdapter<moment.Moment>;
247
```
248

249
[Adapters and Localization](./adapters-localization.md)
250

251
### Validation and Utilities
252

253
Validation functions, utility hooks, and helper components for enhanced picker functionality and custom implementations.
254

255
```typescript { .api }
256
function validateDate<TDate>(props: ValidateDateProps<TDate>): string | null;
257
function validateTime<TDate>(props: ValidateTimeProps<TDate>): string | null;
258
function validateDateTime<TDate>(props: ValidateDateTimeProps<TDate>): string | null;
259

260
function usePickerTranslations(): PickersTranslations;
261
function usePickerAdapter<TDate>(): MuiPickersAdapter<TDate>;
262
function useIsValidValue(props: UseIsValidValueProps): boolean;
263
```
264

265
[Validation and Utilities](./validation-utilities.md)
266

267
## Types
268

269
### Core Picker Types
270

271
```typescript { .api }
272
interface PickerChangeContext {
273
  validationError: string | null;
274
}
275

276
interface FieldChangeContext<TDate> {
277
  validationError: string | null;
278
}
279

280
type PickerValueType = 'date' | 'time' | 'date-time';
281

282
interface PickerOwnerState {
283
  open: boolean;
284
  disabled: boolean;
285
  readOnly: boolean;
286
}
287
```
288

289
### Field Section Types
290

291
```typescript { .api }
292
type FieldSectionType = 'year' | 'month' | 'day' | 'weekDay' | 'hours' | 'minutes' | 'seconds' | 'meridiem' | 'empty';
293
type FieldSectionContentType = 'digit' | 'digit-with-letter' | 'letter';
294
type FieldSelectedSections = number | FieldSectionType | null | 'all';
295

296
interface FieldSection {
297
  value: string;
298
  format: string;
299
  maxLength: number | null;
300
  placeholder: string;
301
  type: FieldSectionType;
302
  contentType: FieldSectionContentType;
303
  hasLeadingZerosInFormat: boolean;
304
  hasLeadingZerosInInput: boolean;
305
  modified: boolean;
306
  startSeparator: string;
307
  endSeparator: string;
308
  isEndFormatSeparator?: boolean;
309
}
310
```
311

312
### Validation Types
313

314
```typescript { .api }
315
interface ValidateDateProps<TDate> {
316
  value: TDate | null;
317
  minDate?: TDate;
318
  maxDate?: TDate;
319
  disableFuture?: boolean;
320
  disablePast?: boolean;
321
  shouldDisableDate?: (day: TDate) => boolean;
322
  adapter: MuiPickersAdapter<TDate>;
323
  timezone: PickersTimezone;
324
}
325

326
interface ValidateTimeProps<TDate> {
327
  value: TDate | null;
328
  minTime?: TDate;
329
  maxTime?: TDate;
330
  shouldDisableTime?: (value: TDate, view: TimeView) => boolean;
331
  adapter: MuiPickersAdapter<TDate>;
332
  timezone: PickersTimezone;
333
}
334

335
interface ValidateDateTimeProps<TDate> extends ValidateDateProps<TDate>, ValidateTimeProps<TDate> {
336
  minDateTime?: TDate;
337
  maxDateTime?: TDate;
338
}
339
```
340

341
## Constants
342

343
```typescript { .api }
344
const DEFAULT_DESKTOP_MODE_MEDIA_QUERY: string;
345
```