0
# Calendar and Clock Components
1

2
Standalone calendar and clock view components for building custom date/time selection interfaces with full customization support.
3

4
## Capabilities
5

6
### DateCalendar
7

8
Standalone calendar component for date selection with month navigation and day selection.
9

10
```typescript { .api }
11
/**
12
 * Standalone calendar component for date selection
13
 * @param props - DateCalendar configuration properties
14
 * @returns JSX element for date calendar
15
 */
16
function DateCalendar<TDate>(props: DateCalendarProps<TDate>): JSX.Element;
17

18
interface DateCalendarProps<TDate> {
19
  /** Current selected date */
20
  value?: TDate | null;
21
  /** Default selected date for uncontrolled component */
22
  defaultValue?: TDate | null;
23
  /** Callback fired when date changes */
24
  onChange?: (value: TDate | null) => void;
25
  /** Available views for the calendar */
26
  views?: readonly DateView[];
27
  /** Currently displayed view */
28
  view?: DateView;
29
  /** Callback when view changes */
30
  onViewChange?: (view: DateView) => void;
31
  /** If true, disable dates after today */
32
  disableFuture?: boolean;
33
  /** If true, disable dates before today */
34
  disablePast?: boolean;
35
  /** Minimum selectable date */
36
  minDate?: TDate;
37
  /** Maximum selectable date */
38
  maxDate?: TDate;
39
  /** Function to disable specific dates */
40
  shouldDisableDate?: (day: TDate) => boolean;
41
  /** Default calendar month when no value is set */
42
  defaultCalendarMonth?: TDate;
43
  /** If true, show days outside current month */
44
  showDaysOutsideCurrentMonth?: boolean;
45
  /** Loading state indicator */
46
  loading?: boolean;
47
  /** Custom render loading component */
48
  renderLoading?: () => React.ReactNode;
49
  /** Custom day rendering function */
50
  renderDay?: (day: TDate, selectedDays: TDate[], pickersDayProps: PickersDayProps<TDate>) => JSX.Element;
51
  /** Component slots for customization */
52
  slots?: DateCalendarSlots<TDate>;
53
  /** Props passed to calendar slots */
54
  slotProps?: DateCalendarSlotProps<TDate>;
55
  /** If true, calendar is read-only */
56
  readOnly?: boolean;
57
  /** If true, calendar is disabled */
58
  disabled?: boolean;
59
  /** Additional CSS classes */
60
  className?: string;
61
  /** Inline styles */
62
  sx?: SxProps<Theme>;
63
}
64

65
interface DateCalendarSlots<TDate> {
66
  switchViewButton?: React.ElementType;
67
  switchViewIcon?: React.ElementType;
68
  previousIconButton?: React.ElementType;
69
  nextIconButton?: React.ElementType;
70
  leftArrowIcon?: React.ElementType;
71
  rightArrowIcon?: React.ElementType;
72
  calendarHeader?: React.ElementType;
73
  day?: React.ElementType;
74
}
75

76
interface DateCalendarSlotProps<TDate> {
77
  switchViewButton?: IconButtonProps;
78
  switchViewIcon?: SvgIconProps;
79
  previousIconButton?: IconButtonProps;
80
  nextIconButton?: IconButtonProps;
81
  leftArrowIcon?: SvgIconProps;
82
  rightArrowIcon?: SvgIconProps;
83
  calendarHeader?: PickersCalendarHeaderSlotProps<TDate>;
84
  day?: PickersDayProps<TDate>;
85
}
86

87
type DateView = 'year' | 'month' | 'day';
88
```
89

90
### MonthCalendar
91

92
Calendar component for month selection with year navigation.
93

94
```typescript { .api }
95
/**
96
 * Calendar component for month selection
97
 * @param props - MonthCalendar configuration properties
98
 * @returns JSX element for month calendar
99
 */
100
function MonthCalendar<TDate>(props: MonthCalendarProps<TDate>): JSX.Element;
101

102
interface MonthCalendarProps<TDate> {
103
  /** Current selected date */
104
  value?: TDate | null;
105
  /** Default selected date for uncontrolled component */
106
  defaultValue?: TDate | null;
107
  /** Callback fired when month changes */
108
  onChange?: (value: TDate | null) => void;
109
  /** If true, disable months after current month */
110
  disableFuture?: boolean;
111
  /** If true, disable months before current month */
112
  disablePast?: boolean;
113
  /** Minimum selectable date */
114
  minDate?: TDate;
115
  /** Maximum selectable date */
116
  maxDate?: TDate;
117
  /** Function to disable specific months */
118
  shouldDisableMonth?: (month: TDate) => boolean;
119
  /** Component slots for customization */
120
  slots?: MonthCalendarSlots<TDate>;
121
  /** Props passed to month calendar slots */
122
  slotProps?: MonthCalendarSlotProps<TDate>;
123
  /** If true, calendar is read-only */
124
  readOnly?: boolean;
125
  /** If true, calendar is disabled */
126
  disabled?: boolean;
127
  /** Additional CSS classes */
128
  className?: string;
129
  /** Inline styles */
130
  sx?: SxProps<Theme>;
131
}
132

133
interface MonthCalendarSlots<TDate> {
134
  monthButton?: React.ElementType;
135
}
136

137
interface MonthCalendarSlotProps<TDate> {
138
  monthButton?: ButtonProps;
139
}
140
```
141

142
### YearCalendar
143

144
Calendar component for year selection with decade navigation.
145

146
```typescript { .api }
147
/**
148
 * Calendar component for year selection
149
 * @param props - YearCalendar configuration properties
150
 * @returns JSX element for year calendar
151
 */
152
function YearCalendar<TDate>(props: YearCalendarProps<TDate>): JSX.Element;
153

154
interface YearCalendarProps<TDate> {
155
  /** Current selected date */
156
  value?: TDate | null;
157
  /** Default selected date for uncontrolled component */
158
  defaultValue?: TDate | null;
159
  /** Callback fired when year changes */
160
  onChange?: (value: TDate | null) => void;
161
  /** If true, disable years after current year */
162
  disableFuture?: boolean;
163
  /** If true, disable years before current year */
164
  disablePast?: boolean;
165
  /** Minimum selectable date */
166
  minDate?: TDate;
167
  /** Maximum selectable date */
168
  maxDate?: TDate;
169
  /** Function to disable specific years */
170
  shouldDisableYear?: (year: TDate) => boolean;
171
  /** Callback when year focus changes */
172
  onYearFocus?: (year: number) => void;
173
  /** Component slots for customization */
174
  slots?: YearCalendarSlots<TDate>;
175
  /** Props passed to year calendar slots */
176
  slotProps?: YearCalendarSlotProps<TDate>;
177
  /** If true, calendar is read-only */
178
  readOnly?: boolean;
179
  /** If true, calendar is disabled */
180
  disabled?: boolean;
181
  /** Additional CSS classes */
182
  className?: string;
183
  /** Inline styles */
184
  sx?: SxProps<Theme>;
185
}
186

187
interface YearCalendarSlots<TDate> {
188
  yearButton?: React.ElementType;
189
}
190

191
interface YearCalendarSlotProps<TDate> {
192
  yearButton?: ButtonProps;
193
}
194
```
195

196
### TimeClock
197

198
Analog clock component for time selection with hour and minute hands.
199

200
```typescript { .api }
201
/**
202
 * Analog clock component for time selection
203
 * @param props - TimeClock configuration properties
204
 * @returns JSX element for time clock
205
 */
206
function TimeClock<TDate>(props: TimeClockProps<TDate>): JSX.Element;
207

208
interface TimeClockProps<TDate> {
209
  /** Current selected time */
210
  value?: TDate | null;
211
  /** Default selected time for uncontrolled component */
212
  defaultValue?: TDate | null;
213
  /** Callback fired when time changes */
214
  onChange?: (value: TDate | null, selectionState?: PickerSelectionState) => void;
215
  /** Available views for the clock */
216
  views?: readonly TimeView[];
217
  /** Currently displayed view */
218
  view?: TimeView;
219
  /** Callback when view changes */
220
  onViewChange?: (view: TimeView) => void;
221
  /** Minimum selectable time */
222
  minTime?: TDate;
223
  /** Maximum selectable time */
224
  maxTime?: TDate;
225
  /** Function to disable specific times */
226
  shouldDisableTime?: (value: TDate, view: TimeView) => boolean;
227
  /** If true, use 12-hour format with AM/PM */
228
  ampm?: boolean;
229
  /** Time step options for different views */
230
  timeSteps?: TimeStepOptions;
231
  /** Component slots for customization */
232
  slots?: TimeClockSlots<TDate>;
233
  /** Props passed to clock slots */
234
  slotProps?: TimeClockSlotProps<TDate>;
235
  /** If true, clock is read-only */
236
  readOnly?: boolean;
237
  /** If true, clock is disabled */
238
  disabled?: boolean;
239
  /** Additional CSS classes */
240
  className?: string;
241
  /** Inline styles */
242
  sx?: SxProps<Theme>;
243
}
244

245
interface TimeClockSlots<TDate> {
246
  clockPointer?: React.ElementType;
247
  clockNumber?: React.ElementType;
248
}
249

250
interface TimeClockSlotProps<TDate> {
251
  clockPointer?: ClockPointerProps;
252
  clockNumber?: ClockNumberProps;
253
}
254

255
type TimeView = 'hours' | 'minutes' | 'seconds';
256
type PickerSelectionState = 'partial' | 'shallow' | 'finish';
257
```
258

259
### DigitalClock
260

261
Digital clock component with scrollable time list selection.
262

263
```typescript { .api }
264
/**
265
 * Digital clock component with scrollable time selection
266
 * @param props - DigitalClock configuration properties
267
 * @returns JSX element for digital clock
268
 */
269
function DigitalClock<TDate>(props: DigitalClockProps<TDate>): JSX.Element;
270

271
interface DigitalClockProps<TDate> {
272
  /** Current selected time */
273
  value?: TDate | null;
274
  /** Default selected time for uncontrolled component */
275
  defaultValue?: TDate | null;
276
  /** Callback fired when time changes */
277
  onChange?: (value: TDate | null, selectionState?: PickerSelectionState) => void;
278
  /** Available views for the clock */
279
  views?: readonly TimeView[];
280
  /** Minimum selectable time */
281
  minTime?: TDate;
282
  /** Maximum selectable time */
283
  maxTime?: TDate;
284
  /** Function to disable specific times */
285
  shouldDisableTime?: (value: TDate, view: TimeView) => boolean;
286
  /** If true, use 12-hour format with AM/PM */
287
  ampm?: boolean;
288
  /** Time step in minutes */
289
  timeStep?: number;
290
  /** Component slots for customization */
291
  slots?: DigitalClockSlots<TDate>;
292
  /** Props passed to digital clock slots */
293
  slotProps?: DigitalClockSlotProps<TDate>;
294
  /** If true, clock is read-only */
295
  readOnly?: boolean;
296
  /** If true, clock is disabled */
297
  disabled?: boolean;
298
  /** Additional CSS classes */
299
  className?: string;
300
  /** Inline styles */
301
  sx?: SxProps<Theme>;
302
}
303

304
interface DigitalClockSlots<TDate> {
305
  digitalClockItem?: React.ElementType;
306
}
307

308
interface DigitalClockSlotProps<TDate> {
309
  digitalClockItem?: DigitalClockItemProps;
310
}
311
```
312

313
### MultiSectionDigitalClock
314

315
Multi-section digital clock with separate columns for hours, minutes, and seconds.
316

317
```typescript { .api }
318
/**
319
 * Multi-section digital clock with separate time columns
320
 * @param props - MultiSectionDigitalClock configuration properties
321
 * @returns JSX element for multi-section digital clock
322
 */
323
function MultiSectionDigitalClock<TDate>(props: MultiSectionDigitalClockProps<TDate>): JSX.Element;
324

325
interface MultiSectionDigitalClockProps<TDate> {
326
  /** Current selected time */
327
  value?: TDate | null;
328
  /** Default selected time for uncontrolled component */
329
  defaultValue?: TDate | null;
330
  /** Callback fired when time changes */
331
  onChange?: (value: TDate | null, selectionState?: PickerSelectionState) => void;
332
  /** Available views for the clock */
333
  views?: readonly TimeView[];
334
  /** Minimum selectable time */
335
  minTime?: TDate;
336
  /** Maximum selectable time */
337
  maxTime?: TDate;
338
  /** Function to disable specific times */
339
  shouldDisableTime?: (value: TDate, view: TimeView) => boolean;
340
  /** If true, use 12-hour format with AM/PM */
341
  ampm?: boolean;
342
  /** Time step options for different views */
343
  timeSteps?: TimeStepOptions;
344
  /** Component slots for customization */
345
  slots?: MultiSectionDigitalClockSlots<TDate>;
346
  /** Props passed to multi-section clock slots */
347
  slotProps?: MultiSectionDigitalClockSlotProps<TDate>;
348
  /** If true, clock is read-only */
349
  readOnly?: boolean;
350
  /** If true, clock is disabled */
351
  disabled?: boolean;
352
  /** Additional CSS classes */
353
  className?: string;
354
  /** Inline styles */
355
  sx?: SxProps<Theme>;
356
}
357

358
interface MultiSectionDigitalClockSlots<TDate> {
359
  digitalClockSectionItem?: React.ElementType;
360
}
361

362
interface MultiSectionDigitalClockSlotProps<TDate> {
363
  digitalClockSectionItem?: MultiSectionDigitalClockSectionProps;
364
}
365
```
366

367
### DayCalendarSkeleton
368

369
Skeleton loading component for calendar views with customizable day structure.
370

371
```typescript { .api }
372
/**
373
 * Skeleton loading component for calendar views
374
 * @param props - DayCalendarSkeleton configuration properties
375
 * @returns JSX element for calendar skeleton
376
 */
377
function DayCalendarSkeleton(props: DayCalendarSkeletonProps): JSX.Element;
378

379
interface DayCalendarSkeletonProps {
380
  /** Additional CSS classes */
381
  className?: string;
382
  /** Inline styles */
383
  sx?: SxProps<Theme>;
384
}
385
```
386

387
**Usage Examples:**
388

389
```typescript
390
import {
391
  DateCalendar,
392
  MonthCalendar,
393
  YearCalendar,
394
  TimeClock,
395
  DigitalClock,
396
  MultiSectionDigitalClock
397
} from '@mui/x-date-pickers';
398
import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
399
import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
400
import dayjs, { Dayjs } from 'dayjs';
401

402
// Custom date selection dashboard
403
function DateSelectionDashboard() {
404
  const [selectedDate, setSelectedDate] = React.useState<Dayjs | null>(dayjs());
405
  const [selectedTime, setSelectedTime] = React.useState<Dayjs | null>(dayjs());
406
  const [view, setView] = React.useState<DateView>('day');
407

408
  return (
409
    <LocalizationProvider dateAdapter={AdapterDayjs}>
410
      <div style={{ display: 'flex', gap: 16 }}>
411
        {/* Date Selection */}
412
        <DateCalendar
413
          value={selectedDate}
414
          onChange={(newValue) => setSelectedDate(newValue)}
415
          view={view}
416
          onViewChange={(newView) => setView(newView)}
417
          views={['year', 'month', 'day']}
418
        />
419
        
420
        {/* Time Selection */}
421
        <TimeClock
422
          value={selectedTime}
423
          onChange={(newValue) => setSelectedTime(newValue)}
424
          views={['hours', 'minutes']}
425
          ampm={false}
426
        />
427
      </div>
428
    </LocalizationProvider>
429
  );
430
}
431

432
// Custom appointment scheduler
433
function AppointmentScheduler() {
434
  const [appointmentTime, setAppointmentTime] = React.useState<Dayjs | null>(null);
435

436
  return (
437
    <LocalizationProvider dateAdapter={AdapterDayjs}>
438
      <MultiSectionDigitalClock
439
        value={appointmentTime}
440
        onChange={(newValue) => setAppointmentTime(newValue)}
441
        views={['hours', 'minutes']}
442
        timeSteps={{ hours: 1, minutes: 15 }}
443
        minTime={dayjs().hour(9).minute(0)}
444
        maxTime={dayjs().hour(17).minute(0)}
445
        ampm={false}
446
      />
447
    </LocalizationProvider>
448
  );
449
}
450
```
451

452
### PickerDay2
453

454
Alternative day component with enhanced visual selection state support.
455

456
```typescript { .api }
457
/**
458
 * Alternative day component with enhanced selection visual states
459
 * @param props - PickerDay2 configuration properties
460
 * @returns JSX element for enhanced day component
461
 */
462
function PickerDay2<TDate>(props: PickerDay2Props<TDate>): JSX.Element;
463

464
interface PickerDay2Props<TDate> extends Omit<PickersDayProps<TDate>, 'classes'> {
465
  /** Override or extend the styles applied to the component */
466
  classes?: Partial<PickerDay2Classes>;
467
  /** Indicates if the day should be visually selected */
468
  isVisuallySelected?: boolean;
469
}
470

471
interface PickerDay2OwnerState<TDate> extends PickerDayOwnerState<TDate> {
472
  /** Whether the day is a filler day (its content is hidden) */
473
  isDayFillerCell: boolean;
474
}
475
```
476

477
### DayCalendarSkeleton
478

479
Loading skeleton component for day calendar while loading state.
480

481
```typescript { .api }
482
/**
483
 * Loading skeleton component for day calendar
484
 * @param props - DayCalendarSkeleton configuration properties
485
 * @returns JSX element for calendar loading skeleton
486
 */
487
function DayCalendarSkeleton(props: DayCalendarSkeletonProps): JSX.Element;
488

489
interface DayCalendarSkeletonProps extends React.JSX.IntrinsicElements['div'] {
490
  /** Override or extend the styles applied to the component */
491
  classes?: Partial<DayCalendarSkeletonClasses>;
492
  /** The system prop that allows defining system overrides as well as additional CSS styles */
493
  sx?: SxProps<Theme>;
494
  /** Ref to the root element */
495
  ref?: React.Ref<HTMLDivElement>;
496
}
497
```
498

499
## CSS Classes
500

501
### DateCalendar Classes
502

503
```typescript { .api }
504
const dateCalendarClasses: {
505
  root: string;
506
  viewTransitionContainer: string;
507
};
508

509
function getDateCalendarUtilityClass(slot: string): string;
510

511
type DateCalendarClassKey = keyof typeof dateCalendarClasses;
512
interface DateCalendarClasses extends Record<DateCalendarClassKey, string> {}
513
```
514

515
### MonthCalendar Classes
516

517
```typescript { .api }
518
const monthCalendarClasses: {
519
  root: string;
520
};
521

522
type MonthCalendarClassKey = keyof typeof monthCalendarClasses;
523
interface MonthCalendarClasses extends Record<MonthCalendarClassKey, string> {}
524
```
525

526
### YearCalendar Classes
527

528
```typescript { .api }
529
const yearCalendarClasses: {
530
  root: string;
531
};
532

533
type YearCalendarClassKey = keyof typeof yearCalendarClasses;
534
interface YearCalendarClasses extends Record<YearCalendarClassKey, string> {}
535
```
536

537
### TimeClock Classes
538

539
```typescript { .api }
540
const timeClockClasses: {
541
  root: string;
542
  clock: string;
543
  wrapper: string;
544
  squareMask: string;
545
  pin: string;
546
  ampmSwitcher: string;
547
  meridiemText: string;
548
};
549

550
type TimeClockClassKey = keyof typeof timeClockClasses;
551
interface TimeClockClasses extends Record<TimeClockClassKey, string> {}
552
```
553

554
### DigitalClock Classes
555

556
```typescript { .api }
557
const digitalClockClasses: {
558
  root: string;
559
  list: string;
560
  item: string;
561
};
562

563
type DigitalClockClassKey = keyof typeof digitalClockClasses;
564
interface DigitalClockClasses extends Record<DigitalClockClassKey, string> {}
565
```
566

567
### MultiSectionDigitalClock Classes
568

569
```typescript { .api }
570
const multiSectionDigitalClockClasses: {
571
  root: string;
572
};
573

574
const multiSectionDigitalClockSectionClasses: {
575
  root: string;
576
  item: string;
577
};
578

579
type MultiSectionDigitalClockClassKey = keyof typeof multiSectionDigitalClockClasses;
580
interface MultiSectionDigitalClockClasses extends Record<MultiSectionDigitalClockClassKey, string> {}
581

582
type MultiSectionDigitalClockSectionClassKey = keyof typeof multiSectionDigitalClockSectionClasses;
583
interface MultiSectionDigitalClockSectionClasses extends Record<MultiSectionDigitalClockSectionClassKey, string> {}
584
```
585

586
### PickerDay2 Classes
587

588
```typescript { .api }
589
const pickerDay2Classes: {
590
  root: string;
591
  dayWithMargin: string;
592
  dayOutsideMonth: string;
593
  hiddenDaySpacingFiller: string;
594
  today: string;
595
  selected: string;
596
  disabled: string;
597
};
598

599
function getPickerDay2UtilityClass(slot: string): string;
600

601
type PickerDay2ClassKey = keyof typeof pickerDay2Classes;
602
interface PickerDay2Classes extends Record<PickerDay2ClassKey, string> {}
603
```
604

605
### DayCalendarSkeleton Classes
606

607
```typescript { .api }
608
const dayCalendarSkeletonClasses: {
609
  root: string;
610
  week: string;
611
  daySkeleton: string;
612
};
613

614
type DayCalendarSkeletonClassKey = keyof typeof dayCalendarSkeletonClasses;
615
interface DayCalendarSkeletonClasses extends Record<DayCalendarSkeletonClassKey, string> {}
616
```
617

618
## Shared Types
619

620
```typescript { .api }
621
interface TimeStepOptions {
622
  hours?: number;
623
  minutes?: number;
624
  seconds?: number;
625
}
626

627
interface PickersDayProps<TDate> {
628
  day: TDate;
629
  selected?: boolean;
630
  disabled?: boolean;
631
  today?: boolean;
632
  outsideCurrentMonth?: boolean;
633
  showDaysOutsideCurrentMonth?: boolean;
634
  onClick?: (day: TDate) => void;
635
  onFocus?: (day: TDate) => void;
636
}
637
```