0
# Date Pickers
1

2
Date picker components provide calendar-based date selection with multiple responsive variants and extensive customization options.
3

4
## Capabilities
5

6
### DatePicker
7

8
Main responsive date picker component that automatically adapts between desktop and mobile interfaces based on screen size.
9

10
```typescript { .api }
11
/**
12
 * Main responsive date picker component
13
 * @param props - DatePicker configuration properties
14
 * @returns JSX element for date picker
15
 */
16
function DatePicker<TDate>(props: DatePickerProps<TDate>): JSX.Element;
17

18
interface DatePickerProps<TDate> {
19
  /** Current date value */
20
  value?: TDate | null;
21
  /** Callback fired when date changes */
22
  onChange?: (value: TDate | null, context: PickerChangeContext) => void;
23
  /** Input label text */
24
  label?: React.ReactNode;
25
  /** If true, the picker is disabled */
26
  disabled?: boolean;
27
  /** If true, the picker is read-only */
28
  readOnly?: boolean;
29
  /** If true, disable dates after today */
30
  disableFuture?: boolean;
31
  /** If true, disable dates before today */
32
  disablePast?: boolean;
33
  /** Minimum selectable date */
34
  minDate?: TDate;
35
  /** Maximum selectable date */  
36
  maxDate?: TDate;
37
  /** Function to disable specific dates */
38
  shouldDisableDate?: (day: TDate) => boolean;
39
  /** Available views for the picker */
40
  views?: readonly DateView[];
41
  /** View to show when picker opens */
42
  openTo?: DateView;
43
  /** Format string for date display */
44
  format?: string;
45
  /** Props passed to picker slots */
46
  slotProps?: DatePickerSlotProps<TDate>;
47
  /** Component slots for customization */
48
  slots?: DatePickerSlots<TDate>;
49
  /** Default calendar month when no value is set */
50
  defaultCalendarMonth?: TDate;
51
  /** If true, show days outside current month */
52
  showDaysOutsideCurrentMonth?: boolean;
53
  /** Loading state indicator */
54
  loading?: boolean;
55
  /** Custom render loading component */
56
  renderLoading?: () => React.ReactNode;
57
  /** Custom day rendering function */
58
  renderDay?: (day: TDate, selectedDays: TDate[], pickersDayProps: PickersDayProps<TDate>) => JSX.Element;
59
}
60

61
interface DatePickerSlots<TDate> {
62
  field?: React.ElementType;
63
  textField?: React.ElementType;
64
  openPickerIcon?: React.ElementType;
65
  switchViewButton?: React.ElementType;
66
  switchViewIcon?: React.ElementType;
67
  previousIconButton?: React.ElementType;
68
  nextIconButton?: React.ElementType;
69
  leftArrowIcon?: React.ElementType;
70
  rightArrowIcon?: React.ElementType;
71
  calendarHeader?: React.ElementType;
72
  day?: React.ElementType;
73
  toolbar?: React.ElementType;
74
  actionBar?: React.ElementType;
75
  shortcuts?: React.ElementType;
76
  layout?: React.ElementType;
77
}
78

79
interface DatePickerSlotProps<TDate> {
80
  field?: PickerFieldSlotProps<TDate>;
81
  textField?: BuiltInFieldTextFieldProps;
82
  openPickerIcon?: IconButtonProps;
83
  switchViewButton?: IconButtonProps;
84
  switchViewIcon?: SvgIconProps;
85
  previousIconButton?: IconButtonProps;
86
  nextIconButton?: IconButtonProps;
87
  leftArrowIcon?: SvgIconProps;
88
  rightArrowIcon?: SvgIconProps;
89
  calendarHeader?: PickersCalendarHeaderSlotProps<TDate>;
90
  day?: PickersDayProps<TDate>;
91
  toolbar?: DatePickerToolbarProps<TDate>;
92
  actionBar?: PickersActionBarProps;
93
  shortcuts?: PickersShortcutsProps<TDate>;
94
  layout?: PickersLayoutSlotProps<TDate>;
95
}
96

97
type DateView = 'year' | 'month' | 'day';
98
```
99

100
**Usage Examples:**
101

102
```typescript
103
import { DatePicker } from '@mui/x-date-pickers/DatePicker';
104
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
105
import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
106
import dayjs, { Dayjs } from 'dayjs';
107

108
// Basic date picker
109
function BasicDatePicker() {
110
  const [value, setValue] = React.useState<Dayjs | null>(null);
111
  
112
  return (
113
    <LocalizationProvider dateAdapter={AdapterDayjs}>
114
      <DatePicker
115
        label="Select date"
116
        value={value}
117
        onChange={(newValue) => setValue(newValue)}
118
      />
119
    </LocalizationProvider>
120
  );
121
}
122

123
// Date picker with validation
124
function ValidatedDatePicker() {
125
  const [value, setValue] = React.useState<Dayjs | null>(null);
126
  
127
  return (
128
    <LocalizationProvider dateAdapter={AdapterDayjs}>
129
      <DatePicker
130
        label="Future dates only"
131
        value={value}
132
        onChange={(newValue) => setValue(newValue)}
133
        disablePast
134
        minDate={dayjs()}
135
        maxDate={dayjs().add(1, 'year')}
136
        shouldDisableDate={(date) => date.day() === 0} // Disable Sundays
137
      />
138
    </LocalizationProvider>
139
  );
140
}
141
```
142

143
### DesktopDatePicker
144

145
Desktop-optimized date picker that always shows the desktop UI regardless of screen size.
146

147
```typescript { .api }
148
/**
149
 * Desktop-optimized date picker with popover interface
150
 * @param props - DesktopDatePicker configuration properties
151
 * @returns JSX element for desktop date picker
152
 */
153
function DesktopDatePicker<TDate>(props: DesktopDatePickerProps<TDate>): JSX.Element;
154

155
interface DesktopDatePickerProps<TDate> extends Omit<DatePickerProps<TDate>, 'slots' | 'slotProps'> {
156
  /** Component slots for desktop customization */
157
  slots?: DesktopDatePickerSlots<TDate>;
158
  /** Props passed to desktop-specific slots */
159
  slotProps?: DesktopDatePickerSlotProps<TDate>;
160
}
161

162
interface DesktopDatePickerSlots<TDate> extends DatePickerSlots<TDate> {
163
  desktopPaper?: React.ElementType;
164
  popper?: React.ElementType;
165
}
166

167
interface DesktopDatePickerSlotProps<TDate> extends DatePickerSlotProps<TDate> {
168
  desktopPaper?: PaperProps;
169
  popper?: PopperProps;
170
}
171
```
172

173
### MobileDatePicker
174

175
Mobile-optimized date picker that always shows the mobile UI with modal interface.
176

177
```typescript { .api }
178
/**
179
 * Mobile-optimized date picker with modal interface
180
 * @param props - MobileDatePicker configuration properties
181
 * @returns JSX element for mobile date picker
182
 */
183
function MobileDatePicker<TDate>(props: MobileDatePickerProps<TDate>): JSX.Element;
184

185
interface MobileDatePickerProps<TDate> extends Omit<DatePickerProps<TDate>, 'slots' | 'slotProps'> {
186
  /** Component slots for mobile customization */
187
  slots?: MobileDatePickerSlots<TDate>;
188
  /** Props passed to mobile-specific slots */
189
  slotProps?: MobileDatePickerSlotProps<TDate>;
190
}
191

192
interface MobileDatePickerSlots<TDate> extends DatePickerSlots<TDate> {
193
  mobilePaper?: React.ElementType;
194
  dialog?: React.ElementType;
195
}
196

197
interface MobileDatePickerSlotProps<TDate> extends DatePickerSlotProps<TDate> {
198
  mobilePaper?: PaperProps;
199
  dialog?: DialogProps;
200
}
201
```
202

203
### StaticDatePicker
204

205
Always-visible date picker without input field, suitable for embedding in forms or dashboards.
206

207
```typescript { .api }
208
/**
209
 * Always-visible date picker without input field
210
 * @param props - StaticDatePicker configuration properties  
211
 * @returns JSX element for static date picker
212
 */
213
function StaticDatePicker<TDate>(props: StaticDatePickerProps<TDate>): JSX.Element;
214

215
interface StaticDatePickerProps<TDate> extends Omit<DatePickerProps<TDate>, 'open' | 'onClose' | 'slots' | 'slotProps'> {
216
  /** Component slots for static customization */
217
  slots?: StaticDatePickerSlots<TDate>;
218
  /** Props passed to static-specific slots */
219
  slotProps?: StaticDatePickerSlotProps<TDate>;
220
  /** Display orientation */
221
  orientation?: 'landscape' | 'portrait';
222
}
223

224
interface StaticDatePickerSlots<TDate> extends Omit<DatePickerSlots<TDate>, 'field' | 'textField' | 'openPickerIcon'> {
225
  staticWrapperInner?: React.ElementType;
226
}
227

228
interface StaticDatePickerSlotProps<TDate> extends Omit<DatePickerSlotProps<TDate>, 'field' | 'textField' | 'openPickerIcon'> {
229
  staticWrapperInner?: React.HTMLAttributes<HTMLDivElement>;
230
}
231
```
232

233
**Usage Examples:**
234

235
```typescript
236
// Static date picker in a dashboard
237
function DashboardDatePicker() {
238
  const [value, setValue] = React.useState<Dayjs | null>(dayjs());
239
  
240
  return (
241
    <LocalizationProvider dateAdapter={AdapterDayjs}>
242
      <StaticDatePicker
243
        value={value}
244
        onChange={(newValue) => setValue(newValue)}
245
        orientation="landscape"
246
      />
247
    </LocalizationProvider>
248
  );
249
}
250
```
251

252
### DatePickerToolbar
253

254
Toolbar component displayed in date pickers showing selected date and view controls.
255

256
```typescript { .api }
257
/**
258
 * Toolbar component for date pickers
259
 * @param props - DatePickerToolbar configuration properties
260
 * @returns JSX element for date picker toolbar
261
 */
262
function DatePickerToolbar<TDate>(props: DatePickerToolbarProps<TDate>): JSX.Element;
263

264
interface DatePickerToolbarProps<TDate> {
265
  /** Current date value */
266
  value?: TDate | null;
267
  /** Currently active view */
268
  view: DateView;
269
  /** Available views */
270
  views: readonly DateView[];
271
  /** Callback when view changes */
272
  onViewChange: (view: DateView) => void;
273
  /** Date adapter instance */
274
  adapter: MuiPickersAdapter<TDate>;
275
  /** Timezone for date operations */
276
  timezone: PickersTimezone;
277
  /** If true, toolbar is hidden */
278
  hidden?: boolean;
279
  /** Additional CSS classes */
280
  className?: string;
281
  /** Inline styles */
282
  sx?: SxProps<Theme>;
283
}
284
```
285

286
## CSS Classes
287

288
### DatePickerToolbar Classes
289

290
```typescript { .api }
291
const datePickerToolbarClasses: {
292
  root: string;
293
  title: string;
294
};
295

296
type DatePickerToolbarClassKey = keyof typeof datePickerToolbarClasses;
297
interface DatePickerToolbarClasses extends Record<DatePickerToolbarClassKey, string> {}
298
```
299

300
## Shared Types
301

302
```typescript { .api }
303
interface PickerChangeContext {
304
  validationError: string | null;
305
}
306

307
interface DatePickerFieldProps<TDate> {
308
  value?: TDate | null;
309
  onChange?: (value: TDate | null, context: FieldChangeContext<TDate>) => void;
310
  format?: string;
311
  disabled?: boolean;
312
  readOnly?: boolean;
313
}
314
```