mui · flaviendelangle · Nov 22, 2023 · Nov 10, 2023 · Nov 10, 2023 · Nov 10, 2023
diff --git a/docs/data/migration/migration-pickers-v6/migration-pickers-v6.md b/docs/data/migration/migration-pickers-v6/migration-pickers-v6.md
@@ -136,6 +136,22 @@ You can read more about the deprecation of this prop in [v6 migration guide](/x/
  />
 ```
 
+### Replace `defaultCalendarMonth` with `referenceDate`
+
+The deprecated `defaultCalendarMonth` prop has been removed in favor of the more flexible `referenceDate` prop.
+
+:::info
+The new `referenceDate` prop is not limited to the default month.
+It will also impact year, day, and time.
+
+Learn more on this prop on [the `DateCalendar` documentation](/x/react-date-pickers/date-calendar/#choose-the-initial-year-month) or [the `referenceDate` documentation](/x/react-date-pickers/base-concepts/#reference-date-when-no-value-is-defined) pages.
+:::
+
+```diff
+- <DateCalendar defaultCalendarMonth={dayjs('2022-04-01')};
++ <DateCalendar referenceDate{dayjs('2022-04-01')} />
+```
+
 ## Modified props
 
 ### Remove the string argument of the `dayOfWeekFormatter` prop

diff --git a/docs/pages/x/api/date-pickers/date-calendar.json b/docs/pages/x/api/date-pickers/date-calendar.json
@@ -10,7 +10,6 @@
         "returned": "string"
       }
     },
-    "defaultCalendarMonth": { "type": { "name": "any" } },
     "defaultValue": { "type": { "name": "any" } },
     "disabled": { "type": { "name": "bool" } },
     "disableFuture": { "type": { "name": "bool" } },

diff --git a/docs/pages/x/api/date-pickers/date-picker.json b/docs/pages/x/api/date-pickers/date-picker.json
@@ -15,7 +15,6 @@
         "returned": "string"
       }
     },
-    "defaultCalendarMonth": { "type": { "name": "any" } },
     "defaultValue": { "type": { "name": "any" } },
     "desktopModeMediaQuery": {
       "type": { "name": "string" },

diff --git a/docs/pages/x/api/date-pickers/date-range-calendar.json b/docs/pages/x/api/date-pickers/date-range-calendar.json
@@ -18,7 +18,6 @@
         "returned": "string"
       }
     },
-    "defaultCalendarMonth": { "type": { "name": "any" } },
     "defaultRangePosition": {
       "type": { "name": "enum", "description": "'end'<br>&#124;&nbsp;'start'" },
       "default": "'start'"

diff --git a/docs/pages/x/api/date-pickers/date-range-picker.json b/docs/pages/x/api/date-pickers/date-range-picker.json
@@ -23,7 +23,6 @@
         "returned": "string"
       }
     },
-    "defaultCalendarMonth": { "type": { "name": "any" } },
     "defaultRangePosition": {
       "type": { "name": "enum", "description": "'end'<br>&#124;&nbsp;'start'" },
       "default": "'start'"

diff --git a/docs/pages/x/api/date-pickers/date-time-picker.json b/docs/pages/x/api/date-pickers/date-time-picker.json
@@ -17,7 +17,6 @@
         "returned": "string"
       }
     },
-    "defaultCalendarMonth": { "type": { "name": "any" } },
     "defaultValue": { "type": { "name": "any" } },
     "desktopModeMediaQuery": {
       "type": { "name": "string" },

diff --git a/docs/pages/x/api/date-pickers/desktop-date-picker.json b/docs/pages/x/api/date-pickers/desktop-date-picker.json
@@ -15,7 +15,6 @@
         "returned": "string"
       }
     },
-    "defaultCalendarMonth": { "type": { "name": "any" } },
     "defaultValue": { "type": { "name": "any" } },
     "disabled": { "type": { "name": "bool" } },
     "disableFuture": { "type": { "name": "bool" } },

diff --git a/docs/pages/x/api/date-pickers/desktop-date-range-picker.json b/docs/pages/x/api/date-pickers/desktop-date-range-picker.json
@@ -23,7 +23,6 @@
         "returned": "string"
       }
     },
-    "defaultCalendarMonth": { "type": { "name": "any" } },
     "defaultRangePosition": {
       "type": { "name": "enum", "description": "'end'<br>&#124;&nbsp;'start'" },
       "default": "'start'"

diff --git a/docs/pages/x/api/date-pickers/desktop-date-time-picker.json b/docs/pages/x/api/date-pickers/desktop-date-time-picker.json
@@ -17,7 +17,6 @@
         "returned": "string"
       }
     },
-    "defaultCalendarMonth": { "type": { "name": "any" } },
     "defaultValue": { "type": { "name": "any" } },
     "disabled": { "type": { "name": "bool" } },
     "disableFuture": { "type": { "name": "bool" } },

diff --git a/docs/pages/x/api/date-pickers/mobile-date-picker.json b/docs/pages/x/api/date-pickers/mobile-date-picker.json
@@ -15,7 +15,6 @@
         "returned": "string"
       }
     },
-    "defaultCalendarMonth": { "type": { "name": "any" } },
     "defaultValue": { "type": { "name": "any" } },
     "disabled": { "type": { "name": "bool" } },
     "disableFuture": { "type": { "name": "bool" } },

diff --git a/docs/pages/x/api/date-pickers/mobile-date-range-picker.json b/docs/pages/x/api/date-pickers/mobile-date-range-picker.json
@@ -23,7 +23,6 @@
         "returned": "string"
       }
     },
-    "defaultCalendarMonth": { "type": { "name": "any" } },
     "defaultRangePosition": {
       "type": { "name": "enum", "description": "'end'<br>&#124;&nbsp;'start'" },
       "default": "'start'"

diff --git a/docs/pages/x/api/date-pickers/mobile-date-time-picker.json b/docs/pages/x/api/date-pickers/mobile-date-time-picker.json
@@ -17,7 +17,6 @@
         "returned": "string"
       }
     },
-    "defaultCalendarMonth": { "type": { "name": "any" } },
     "defaultValue": { "type": { "name": "any" } },
     "disabled": { "type": { "name": "bool" } },
     "disableFuture": { "type": { "name": "bool" } },

diff --git a/docs/pages/x/api/date-pickers/static-date-picker.json b/docs/pages/x/api/date-pickers/static-date-picker.json
@@ -11,7 +11,6 @@
         "returned": "string"
       }
     },
-    "defaultCalendarMonth": { "type": { "name": "any" } },
     "defaultValue": { "type": { "name": "any" } },
     "disabled": { "type": { "name": "bool" } },
     "disableFuture": { "type": { "name": "bool" } },

diff --git a/docs/pages/x/api/date-pickers/static-date-range-picker.json b/docs/pages/x/api/date-pickers/static-date-range-picker.json
@@ -19,7 +19,6 @@
         "returned": "string"
       }
     },
-    "defaultCalendarMonth": { "type": { "name": "any" } },
     "defaultRangePosition": {
       "type": { "name": "enum", "description": "'end'<br>&#124;&nbsp;'start'" },
       "default": "'start'"

diff --git a/docs/pages/x/api/date-pickers/static-date-time-picker.json b/docs/pages/x/api/date-pickers/static-date-time-picker.json
@@ -13,7 +13,6 @@
         "returned": "string"
       }
     },
-    "defaultCalendarMonth": { "type": { "name": "any" } },
     "defaultValue": { "type": { "name": "any" } },
     "disabled": { "type": { "name": "bool" } },
     "disableFuture": { "type": { "name": "bool" } },

diff --git a/docs/translations/api-docs/date-pickers/date-calendar.json b/docs/translations/api-docs/date-pickers/date-calendar.json
@@ -14,11 +14,6 @@
         "string": "The name to display."
       }
     },
-    "defaultCalendarMonth": {
-      "description": "Default calendar month displayed when <code>value</code> and <code>defaultValue</code> are empty.",
-      "deprecated": "",
-      "typeDescriptions": {}
-    },
     "defaultValue": {
       "description": "The default selected value. Used when the component is not controlled.",
       "deprecated": "",

diff --git a/docs/translations/api-docs/date-pickers/date-picker.json b/docs/translations/api-docs/date-pickers/date-picker.json
@@ -24,11 +24,6 @@
         "string": "The name to display."
       }
     },
-    "defaultCalendarMonth": {
-      "description": "Default calendar month displayed when <code>value</code> and <code>defaultValue</code> are empty.",
-      "deprecated": "",
-      "typeDescriptions": {}
-    },
     "defaultValue": {
       "description": "The default value. Used when the component is not controlled.",
       "deprecated": "",

diff --git a/docs/translations/api-docs/date-pickers/date-range-calendar.json b/docs/translations/api-docs/date-pickers/date-range-calendar.json
@@ -24,11 +24,6 @@
         "string": "The name to display."
       }
     },
-    "defaultCalendarMonth": {
-      "description": "Default calendar month displayed when <code>value={[null, null]}</code>.",
-      "deprecated": "",
-      "typeDescriptions": {}
-    },
     "defaultRangePosition": {
       "description": "The initial position in the edited date range. Used when the component is not controlled.",
       "deprecated": "",

diff --git a/docs/translations/api-docs/date-pickers/date-range-picker.json b/docs/translations/api-docs/date-pickers/date-range-picker.json
@@ -34,11 +34,6 @@
         "string": "The name to display."
       }
     },
-    "defaultCalendarMonth": {
-      "description": "Default calendar month displayed when <code>value={[null, null]}</code>.",
-      "deprecated": "",
-      "typeDescriptions": {}
-    },
     "defaultRangePosition": {
       "description": "The initial position in the edited date range. Used when the component is not controlled.",
       "deprecated": "",

diff --git a/docs/translations/api-docs/date-pickers/date-time-picker.json b/docs/translations/api-docs/date-pickers/date-time-picker.json
@@ -34,11 +34,6 @@
         "string": "The name to display."
       }
     },
-    "defaultCalendarMonth": {
-      "description": "Default calendar month displayed when <code>value</code> and <code>defaultValue</code> are empty.",
-      "deprecated": "",
-      "typeDescriptions": {}
-    },
     "defaultValue": {
       "description": "The default value. Used when the component is not controlled.",
       "deprecated": "",

diff --git a/docs/translations/api-docs/date-pickers/desktop-date-picker.json b/docs/translations/api-docs/date-pickers/desktop-date-picker.json
@@ -24,11 +24,6 @@
         "string": "The name to display."
       }
     },
-    "defaultCalendarMonth": {
-      "description": "Default calendar month displayed when <code>value</code> and <code>defaultValue</code> are empty.",
-      "deprecated": "",
-      "typeDescriptions": {}
-    },
     "defaultValue": {
       "description": "The default value. Used when the component is not controlled.",
       "deprecated": "",

diff --git a/docs/translations/api-docs/date-pickers/desktop-date-range-picker.json b/docs/translations/api-docs/date-pickers/desktop-date-range-picker.json
@@ -34,11 +34,6 @@
         "string": "The name to display."
       }
     },
-    "defaultCalendarMonth": {
-      "description": "Default calendar month displayed when <code>value={[null, null]}</code>.",
-      "deprecated": "",
-      "typeDescriptions": {}
-    },
     "defaultRangePosition": {
       "description": "The initial position in the edited date range. Used when the component is not controlled.",
       "deprecated": "",

diff --git a/docs/translations/api-docs/date-pickers/desktop-date-time-picker.json b/docs/translations/api-docs/date-pickers/desktop-date-time-picker.json
@@ -34,11 +34,6 @@
         "string": "The name to display."
       }
     },
-    "defaultCalendarMonth": {
-      "description": "Default calendar month displayed when <code>value</code> and <code>defaultValue</code> are empty.",
-      "deprecated": "",
-      "typeDescriptions": {}
-    },
     "defaultValue": {
       "description": "The default value. Used when the component is not controlled.",
       "deprecated": "",

diff --git a/docs/translations/api-docs/date-pickers/mobile-date-picker.json b/docs/translations/api-docs/date-pickers/mobile-date-picker.json
@@ -24,11 +24,6 @@
         "string": "The name to display."
       }
     },
-    "defaultCalendarMonth": {
-      "description": "Default calendar month displayed when <code>value</code> and <code>defaultValue</code> are empty.",
-      "deprecated": "",
-      "typeDescriptions": {}
-    },
     "defaultValue": {
       "description": "The default value. Used when the component is not controlled.",
       "deprecated": "",

diff --git a/docs/translations/api-docs/date-pickers/mobile-date-range-picker.json b/docs/translations/api-docs/date-pickers/mobile-date-range-picker.json
@@ -34,11 +34,6 @@
         "string": "The name to display."
       }
     },
-    "defaultCalendarMonth": {
-      "description": "Default calendar month displayed when <code>value={[null, null]}</code>.",
-      "deprecated": "",
-      "typeDescriptions": {}
-    },
     "defaultRangePosition": {
       "description": "The initial position in the edited date range. Used when the component is not controlled.",
       "deprecated": "",

diff --git a/docs/translations/api-docs/date-pickers/mobile-date-time-picker.json b/docs/translations/api-docs/date-pickers/mobile-date-time-picker.json
@@ -34,11 +34,6 @@
         "string": "The name to display."
       }
     },
-    "defaultCalendarMonth": {
-      "description": "Default calendar month displayed when <code>value</code> and <code>defaultValue</code> are empty.",
-      "deprecated": "",
-      "typeDescriptions": {}
-    },
     "defaultValue": {
       "description": "The default value. Used when the component is not controlled.",
       "deprecated": "",

diff --git a/docs/translations/api-docs/date-pickers/static-date-picker.json b/docs/translations/api-docs/date-pickers/static-date-picker.json
@@ -19,11 +19,6 @@
         "string": "The name to display."
       }
     },
-    "defaultCalendarMonth": {
-      "description": "Default calendar month displayed when <code>value</code> and <code>defaultValue</code> are empty.",
-      "deprecated": "",
-      "typeDescriptions": {}
-    },
     "defaultValue": {
       "description": "The default value. Used when the component is not controlled.",
       "deprecated": "",

diff --git a/docs/translations/api-docs/date-pickers/static-date-range-picker.json b/docs/translations/api-docs/date-pickers/static-date-range-picker.json
@@ -29,11 +29,6 @@
         "string": "The name to display."
       }
     },
-    "defaultCalendarMonth": {
-      "description": "Default calendar month displayed when <code>value={[null, null]}</code>.",
-      "deprecated": "",
-      "typeDescriptions": {}
-    },
     "defaultRangePosition": {
       "description": "The initial position in the edited date range. Used when the component is not controlled.",
       "deprecated": "",

diff --git a/docs/translations/api-docs/date-pickers/static-date-time-picker.json b/docs/translations/api-docs/date-pickers/static-date-time-picker.json
@@ -29,11 +29,6 @@
         "string": "The name to display."
       }
     },
-    "defaultCalendarMonth": {
-      "description": "Default calendar month displayed when <code>value</code> and <code>defaultValue</code> are empty.",
-      "deprecated": "",
-      "typeDescriptions": {}
-    },
     "defaultValue": {
       "description": "The default value. Used when the component is not controlled.",
       "deprecated": "",

diff --git a/packages/x-date-pickers-pro/src/DateRangeCalendar/DateRangeCalendar.test.tsx b/packages/x-date-pickers-pro/src/DateRangeCalendar/DateRangeCalendar.test.tsx
@@ -87,10 +87,7 @@ describe('<DateRangeCalendar />', () => {
       const onChange = spy();
 
       render(
-        <DateRangeCalendar
-          onChange={onChange}
-          defaultCalendarMonth={adapterToUse.date('2019-01-01')}
-        />,
+        <DateRangeCalendar onChange={onChange} referenceDate={adapterToUse.date('2019-01-01')} />,
       );
 
       fireEvent.click(getPickerDay('30', 'January 2019'));

diff --git a/packages/x-date-pickers-pro/src/DateRangeCalendar/DateRangeCalendar.tsx b/packages/x-date-pickers-pro/src/DateRangeCalendar/DateRangeCalendar.tsx
@@ -188,7 +188,6 @@ const DateRangeCalendar = React.forwardRef(function DateRangeCalendar<TDate>(
     shouldDisableDate,
     reduceAnimations,
     onMonthChange,
-    defaultCalendarMonth,
     rangePosition: rangePositionProp,
     defaultRangePosition: inDefaultRangePosition,
     onRangePositionChange: inOnRangePositionChange,
@@ -324,7 +323,6 @@ const DateRangeCalendar = React.forwardRef(function DateRangeCalendar<TDate>(
   } = useCalendarState<TDate>({
     value: value[0] || value[1],
     referenceDate,
-    defaultCalendarMonth,
     disableFuture,
     disablePast,
     disableSwitchToMonthOnDayFocus: true,
@@ -642,10 +640,6 @@ DateRangeCalendar.propTypes = {
    * @default (_day: string, date: TDate) => adapter.format(date, 'weekdayShort').charAt(0).toUpperCase()
    */
   dayOfWeekFormatter: PropTypes.func,
-  /**
-   * Default calendar month displayed when `value={[null, null]}`.
-   */
-  defaultCalendarMonth: PropTypes.any,
   /**
    * The initial position in the edited date range.
    * Used when the component is not controlled.

diff --git a/packages/x-date-pickers-pro/src/DateRangeCalendar/DateRangeCalendar.types.ts b/packages/x-date-pickers-pro/src/DateRangeCalendar/DateRangeCalendar.types.ts
@@ -74,10 +74,6 @@ export interface ExportedDateRangeCalendarProps<TDate>
    * @default false
    */
   disableAutoMonthSwitching?: boolean;
-  /**
-   * Default calendar month displayed when `value={[null, null]}`.
-   */
-  defaultCalendarMonth?: TDate;
   /**
    * If `true`, the picker and text field are disabled.
    * @default false

diff --git a/packages/x-date-pickers-pro/src/DateRangePicker/DateRangePicker.tsx b/packages/x-date-pickers-pro/src/DateRangePicker/DateRangePicker.tsx
@@ -77,10 +77,6 @@ DateRangePicker.propTypes = {
    * @default (_day: string, date: TDate) => adapter.format(date, 'weekdayShort').charAt(0).toUpperCase()
    */
   dayOfWeekFormatter: PropTypes.func,
-  /**
-   * Default calendar month displayed when `value={[null, null]}`.
-   */
-  defaultCalendarMonth: PropTypes.any,
   /**
    * The initial position in the edited date range.
    * Used when the component is not controlled.

diff --git a/packages/x-date-pickers-pro/src/DesktopDateRangePicker/DesktopDateRangePicker.tsx b/packages/x-date-pickers-pro/src/DesktopDateRangePicker/DesktopDateRangePicker.tsx
@@ -113,10 +113,6 @@ DesktopDateRangePicker.propTypes = {
    * @default (_day: string, date: TDate) => adapter.format(date, 'weekdayShort').charAt(0).toUpperCase()
    */
   dayOfWeekFormatter: PropTypes.func,
-  /**
-   * Default calendar month displayed when `value={[null, null]}`.
-   */
-  defaultCalendarMonth: PropTypes.any,
   /**
    * The initial position in the edited date range.
    * Used when the component is not controlled.

diff --git a/packages/x-date-pickers-pro/src/MobileDateRangePicker/MobileDateRangePicker.tsx b/packages/x-date-pickers-pro/src/MobileDateRangePicker/MobileDateRangePicker.tsx
@@ -113,10 +113,6 @@ MobileDateRangePicker.propTypes = {
    * @default (_day: string, date: TDate) => adapter.format(date, 'weekdayShort').charAt(0).toUpperCase()
    */
   dayOfWeekFormatter: PropTypes.func,
-  /**
-   * Default calendar month displayed when `value={[null, null]}`.
-   */
-  defaultCalendarMonth: PropTypes.any,
   /**
    * The initial position in the edited date range.
    * Used when the component is not controlled.

diff --git a/packages/x-date-pickers-pro/src/StaticDateRangePicker/StaticDateRangePicker.tsx b/packages/x-date-pickers-pro/src/StaticDateRangePicker/StaticDateRangePicker.tsx
@@ -100,10 +100,6 @@ StaticDateRangePicker.propTypes = {
    * @default (_day: string, date: TDate) => adapter.format(date, 'weekdayShort').charAt(0).toUpperCase()
    */
   dayOfWeekFormatter: PropTypes.func,
-  /**
-   * Default calendar month displayed when `value={[null, null]}`.
-   */
-  defaultCalendarMonth: PropTypes.any,
   /**
    * The initial position in the edited date range.
    * Used when the component is not controlled.