[pickers] Allow to customize the month and the year buttons

docs/data/date-pickers/custom-components/custom-components.md

@@ -1,7 +1,7 @@
 ---
 productId: x-date-pickers
 title: Date and Time Pickers - Custom slots and subcomponents
-components: DateTimePickerTabs, PickersActionBar, DatePickerToolbar, TimePickerToolbar, DateTimePickerToolbar, PickersCalendarHeader, PickersRangeCalendarHeader, PickersShortcuts, DateRangePickerToolbar
+components: DateTimePickerTabs, PickersActionBar, DatePickerToolbar, TimePickerToolbar, DateTimePickerToolbar, PickersShortcuts, DateRangePickerToolbar
 ---
 
 # Custom slots and subcomponents
@@ -219,34 +219,6 @@ Each component comes with its own toolbar (`DatePickerToolbar`, `TimePickerToolb
 
 {{"demo": "ToolbarComponent.js"}}
 
-## Calendar header
-
-The calendar header is available on any component that renders a calendar to select a date or a range of dates.
-It allows the user to navigate through months and to switch to the month and year views when available.
-
-### Component props
-
-You can pass props to the calendar header as shown below:
-
-{{"demo": "CalendarHeaderComponentProps.js", "defaultCodeOpen": false}}
-
-### Component
-
-You can pass custom components to replace the header, as shown below:
-
-{{"demo": "CalendarHeaderComponent.js", "defaultCodeOpen": false}}
-
-When used with a date range component,
-you receive three additional props to let you handle scenarios where multiple months are rendered:
-
-- `calendars`: The number of calendars rendered
-- `month`: The month used for the header being rendered
-- `monthIndex`: The index of the month used for the header being rendered
-
-The demo below shows how to navigate the months two by two:
-
-{{"demo": "CalendarHeaderComponentRange.js", "defaultCodeOpen": false}}
-
 ## Arrow switcher
 
 The following slots let you customize how to render the buttons and icons for an arrow switcher component—the component

docs/data/date-pickers/custom-views/MonthButtonComponent.js

@@ -0,0 +1,26 @@
+import * as React from 'react';
+import { styled } from '@mui/material/styles';
+import { DemoContainer } from '@mui/x-date-pickers/internals/demo';
+import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
+import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
+import { DateCalendar } from '@mui/x-date-pickers/DateCalendar';
+
+const CustomMonthButton = styled('button')({
+  margin: '8px 0',
+  height: 36,
+  width: 72,
+});
+
+export default function MonthButtonComponent() {
+  return (
+    <LocalizationProvider dateAdapter={AdapterDayjs}>
+      <DemoContainer components={['DateCalendar']}>
+        <DateCalendar
+          slots={{ monthButton: CustomMonthButton }}
+          views={['month', 'day']}
+          openTo="month"
+        />
+      </DemoContainer>
+    </LocalizationProvider>
+  );
+}

docs/data/date-pickers/custom-views/MonthButtonComponent.tsx

@@ -0,0 +1,26 @@
+import * as React from 'react';
+import { styled } from '@mui/material/styles';
+import { DemoContainer } from '@mui/x-date-pickers/internals/demo';
+import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
+import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
+import { DateCalendar } from '@mui/x-date-pickers/DateCalendar';
+
+const CustomMonthButton = styled('button')({
+  margin: '8px 0',
+  height: 36,
+  width: 72,
+});
+
+export default function MonthButtonComponent() {
+  return (
+    <LocalizationProvider dateAdapter={AdapterDayjs}>
+      <DemoContainer components={['DateCalendar']}>
+        <DateCalendar
+          slots={{ monthButton: CustomMonthButton }}
+          views={['month', 'day']}
+          openTo="month"
+        />
+      </DemoContainer>
+    </LocalizationProvider>
+  );
+}

docs/data/date-pickers/custom-views/MonthButtonComponent.tsx.preview

@@ -0,0 +1,5 @@
+<DateCalendar
+  slots={{ monthButton: CustomMonthButton }}
+  views={['month', 'day']}
+  openTo="month"
+/>

docs/data/date-pickers/custom-views/MonthButtonComponentProps.js

@@ -0,0 +1,23 @@
+import * as React from 'react';
+import { DemoContainer } from '@mui/x-date-pickers/internals/demo';
+import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
+import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
+import { DateCalendar } from '@mui/x-date-pickers/DateCalendar';
+
+export default function MonthButtonComponentProps() {
+  return (
+    <LocalizationProvider dateAdapter={AdapterDayjs}>
+      <DemoContainer components={['DateCalendar']}>
+        <DateCalendar
+          slotProps={{
+            monthButton: (ownerState) => ({
+              title: ownerState['aria-label'],
+            }),
+          }}
+          views={['month', 'day']}
+          openTo="month"
+        />
+      </DemoContainer>
+    </LocalizationProvider>
+  );
+}

docs/data/date-pickers/custom-views/MonthButtonComponentProps.tsx

@@ -0,0 +1,23 @@
+import * as React from 'react';
+import { DemoContainer } from '@mui/x-date-pickers/internals/demo';
+import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
+import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
+import { DateCalendar } from '@mui/x-date-pickers/DateCalendar';
+
+export default function MonthButtonComponentProps() {
+  return (
+    <LocalizationProvider dateAdapter={AdapterDayjs}>
+      <DemoContainer components={['DateCalendar']}>
+        <DateCalendar
+          slotProps={{
+            monthButton: (ownerState) => ({
+              title: ownerState['aria-label'],
+            }),
+          }}
+          views={['month', 'day']}
+          openTo="month"
+        />
+      </DemoContainer>
+    </LocalizationProvider>
+  );
+}

docs/data/date-pickers/custom-views/MonthButtonComponentProps.tsx.preview

@@ -0,0 +1,9 @@
+<DateCalendar
+  slotProps={{
+    monthButton: (ownerState) => ({
+      title: ownerState['aria-label'],
+    }),
+  }}
+  views={['month', 'day']}
+  openTo="month"
+/>

docs/data/date-pickers/custom-views/custom-views.md

@@ -0,0 +1,51 @@
+---
+productId: x-date-pickers
+title: Date and Time Pickers - Custom views
+components: PickersCalendarHeader, PickersRangeCalendarHeader, PickersMonth
+---
+
+# Custom views
+
+<p class="description">Learn how to override the default DOM structure of the views.</p>
+
+## Calendar header
+
+The calendar header is available on any component that renders a calendar to select a date or a range of dates.
+It allows the user to navigate through months and to switch to the month and year views when available.
+
+### Component props
+
+You can pass props to the calendar header as shown below:
+
+{{"demo": "CalendarHeaderComponentProps.js", "defaultCodeOpen": false}}
+
+### Component
+
+You can pass custom components to replace the header, as shown below:
+
+{{"demo": "CalendarHeaderComponent.js", "defaultCodeOpen": false}}
+
+When used with a date range component,
+you receive three additional props to let you handle scenarios where multiple months are rendered:
+
+- `calendars`: The number of calendars rendered
+- `month`: The month used for the header being rendered
+- `monthIndex`: The index of the month used for the header being rendered
+
+The demo below shows how to navigate the months two by two:
+
+{{"demo": "CalendarHeaderComponentRange.js", "defaultCodeOpen": false}}
+
+## Month button
+
+### Component props
+
+You can pass props to the month button as shown below:
+
+{{"demo": "MonthButtonComponentProps.js"}}
+
+### Component
+
+You can pass custom components to replace the month button, as shown below:
+
+{{"demo": "MonthButtonComponent.js"}}

docs/data/pages.ts

@@ -366,6 +366,7 @@ const pages: MuiPage[] = [
             title: 'Custom slots and subcomponents',
           },
           { pathname: '/x/react-date-pickers/custom-layout' },
+          { pathname: '/x/react-date-pickers/custom-views' },
           { pathname: '/x/react-date-pickers/custom-field' },
           { pathname: '/x/react-date-pickers/custom-opening-button' },
           { pathname: '/x/react-date-pickers/playground', title: 'Customization playground' },

docs/pages/x/api/date-pickers/date-calendar.json

@@ -199,6 +199,12 @@
       "description": "Custom component for day.\nCheck the [PickersDay](https://mui.com/x/api/date-pickers/pickers-day/) component.",
       "default": "PickersDay",
       "class": null
+    },
+    {
+      "name": "monthButton",
+      "description": "Button displayed to render a single month in the \"month\" view .",
+      "default": "MonthCalendarButton",
+      "class": null
     }
   ],
   "classes": [

docs/pages/x/api/date-pickers/date-picker.json

@@ -242,6 +242,12 @@
       "default": "PickersDay",
       "class": null
     },
+    {
+      "name": "monthButton",
+      "description": "Button displayed to render a single month in the \"month\" view .",
+      "default": "MonthCalendarButton",
+      "class": null
+    },
     {
       "name": "actionBar",
       "description": "Custom component for the action bar, it is placed below the picker views.",

docs/pages/x/api/date-pickers/date-time-picker.json

@@ -276,6 +276,12 @@
       "default": "PickersDay",
       "class": null
     },
+    {
+      "name": "monthButton",
+      "description": "Button displayed to render a single month in the \"month\" view .",
+      "default": "MonthCalendarButton",
+      "class": null
+    },
     {
       "name": "actionBar",
       "description": "Custom component for the action bar, it is placed below the picker views.",

docs/pages/x/api/date-pickers/desktop-date-picker.json

@@ -238,6 +238,12 @@
       "default": "PickersDay",
       "class": null
     },
+    {
+      "name": "monthButton",
+      "description": "Button displayed to render a single month in the \"month\" view .",
+      "default": "MonthCalendarButton",
+      "class": null
+    },
     {
       "name": "actionBar",
       "description": "Custom component for the action bar, it is placed below the picker views.",

docs/pages/x/api/date-pickers/desktop-date-time-picker.json

@@ -272,6 +272,12 @@
       "default": "PickersDay",
       "class": null
     },
+    {
+      "name": "monthButton",
+      "description": "Button displayed to render a single month in the \"month\" view .",
+      "default": "MonthCalendarButton",
+      "class": null
+    },
     {
       "name": "actionBar",
       "description": "Custom component for the action bar, it is placed below the picker views.",

docs/pages/x/api/date-pickers/mobile-date-picker.json

@@ -238,6 +238,12 @@
       "default": "PickersDay",
       "class": null
     },
+    {
+      "name": "monthButton",
+      "description": "Button displayed to render a single month in the \"month\" view .",
+      "default": "MonthCalendarButton",
+      "class": null
+    },
     {
       "name": "actionBar",
       "description": "Custom component for the action bar, it is placed below the picker views.",

docs/pages/x/api/date-pickers/mobile-date-time-picker.json

@@ -263,6 +263,12 @@
       "default": "PickersDay",
       "class": null
     },
+    {
+      "name": "monthButton",
+      "description": "Button displayed to render a single month in the \"month\" view .",
+      "default": "MonthCalendarButton",
+      "class": null
+    },
     {
       "name": "actionBar",
       "description": "Custom component for the action bar, it is placed below the picker views.",

docs/pages/x/api/date-pickers/month-calendar.json

@@ -29,6 +29,12 @@
         "returned": "boolean"
       }
     },
+    "slotProps": { "type": { "name": "object" }, "default": "{}" },
+    "slots": {
+      "type": { "name": "object" },
+      "default": "{}",
+      "additionalInfo": { "slotsApi": true }
+    },
     "sx": {
       "type": {
         "name": "union",
@@ -52,6 +58,14 @@
     "import { MonthCalendar } from '@mui/x-date-pickers';",
     "import { MonthCalendar } from '@mui/x-date-pickers-pro';"
   ],
+  "slots": [
+    {
+      "name": "monthButton",
+      "description": "Button displayed to render a single month in the \"month\" view .",
+      "default": "MonthCalendarButton",
+      "class": null
+    }
+  ],
   "classes": [
     {
       "key": "root",

docs/pages/x/api/date-pickers/pickers-calendar-header.json

@@ -86,6 +86,6 @@
   "muiName": "MuiPickersCalendarHeader",
   "filename": "/packages/x-date-pickers/src/PickersCalendarHeader/PickersCalendarHeader.tsx",
   "inheritance": null,
-  "demos": "<ul><li><a href=\"/x/react-date-pickers/custom-components/\">Custom slots and subcomponents</a></li></ul>",
+  "demos": "<ul><li><a href=\"/x/react-date-pickers/custom-views/\">Custom views</a></li></ul>",
   "cssComponent": false
 }

docs/pages/x/api/date-pickers/pickers-range-calendar-header.json

@@ -65,6 +65,6 @@
   "muiName": "MuiPickersRangeCalendarHeader",
   "filename": "/packages/x-date-pickers-pro/src/PickersRangeCalendarHeader/PickersRangeCalendarHeader.tsx",
   "inheritance": null,
-  "demos": "<ul><li><a href=\"/x/react-date-pickers/custom-components/\">Custom slots and subcomponents</a></li></ul>",
+  "demos": "<ul><li><a href=\"/x/react-date-pickers/custom-views/\">Custom views</a></li></ul>",
   "cssComponent": false
 }

docs/pages/x/api/date-pickers/static-date-picker.json

@@ -218,6 +218,12 @@
       "default": "PickersDay",
       "class": null
     },
+    {
+      "name": "monthButton",
+      "description": "Button displayed to render a single month in the \"month\" view .",
+      "default": "MonthCalendarButton",
+      "class": null
+    },
     {
       "name": "actionBar",
       "description": "Custom component for the action bar, it is placed below the picker views.",

docs/pages/x/api/date-pickers/static-date-time-picker.json

@@ -243,6 +243,12 @@
       "default": "PickersDay",
       "class": null
     },
+    {
+      "name": "monthButton",
+      "description": "Button displayed to render a single month in the \"month\" view .",
+      "default": "MonthCalendarButton",
+      "class": null
+    },
     {
       "name": "actionBar",
       "description": "Custom component for the action bar, it is placed below the picker views.",

docs/pages/x/react-date-pickers/custom-views.js

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import * as pageProps from 'docsx/data/date-pickers/custom-views/custom-views.md?muiMarkdown';
+
+export default function Page() {
+  return <MarkdownDocs {...pageProps} />;
+}