[docs] Add section about overriding slots to base concepts (#10421)

Signed-off-by: Nora <[email protected]> Co-authored-by: Lukas <[email protected]> Co-authored-by: Sam Sycamore <[email protected]>
mui · Oct 4, 2023 · 8cafb55 · 8cafb55
1 parent d3bca9c
commit 8cafb55
Show file tree

Hide file tree

Showing 12 changed files with 122 additions and 13 deletions.
diff --git a/docs/data/date-pickers/base-concepts/CustomSlots.js b/docs/data/date-pickers/base-concepts/CustomSlots.js
@@ -0,0 +1,46 @@
+import * as React from 'react';
+import { DemoContainer } from '@mui/x-date-pickers/internals/demo';
+import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
+import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
+import { DatePicker } from '@mui/x-date-pickers/DatePicker';
+import { PickersDay } from '@mui/x-date-pickers/PickersDay';
+import EditCalendarRoundedIcon from '@mui/icons-material/EditCalendarRounded';
+import { styled } from '@mui/material/styles';
+import IconButton from '@mui/material/IconButton';
+
+const StyledButton = styled(IconButton)(({ theme }) => ({
+  borderRadius: theme.shape.borderRadius,
+}));
+const StyledDay = styled(PickersDay)(({ theme }) => ({
+  borderRadius: theme.shape.borderRadius,
+  color:
+    theme.palette.mode === 'light'
+      ? theme.palette.secondary.dark
+      : theme.palette.secondary.light,
+}));
+
+export default function CustomSlots() {
+  return (
+    <LocalizationProvider dateAdapter={AdapterDayjs}>
+      <DemoContainer components={['DatePicker']}>
+        <DatePicker
+          label="Styled picker"
+          slots={{
+            openPickerIcon: EditCalendarRoundedIcon,
+            openPickerButton: StyledButton,
+            day: StyledDay,
+          }}
+          slotProps={{
+            openPickerIcon: { fontSize: 'large' },
+            openPickerButton: { color: 'secondary' },
+            textField: {
+              variant: 'filled',
+              focused: true,
+              color: 'secondary',
+            },
+          }}
+        />
+      </DemoContainer>
+    </LocalizationProvider>
+  );
+}
diff --git a/docs/data/date-pickers/base-concepts/CustomSlots.tsx b/docs/data/date-pickers/base-concepts/CustomSlots.tsx
@@ -0,0 +1,46 @@
+import * as React from 'react';
+import { DemoContainer } from '@mui/x-date-pickers/internals/demo';
+import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
+import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
+import { DatePicker } from '@mui/x-date-pickers/DatePicker';
+import { PickersDay } from '@mui/x-date-pickers/PickersDay';
+import EditCalendarRoundedIcon from '@mui/icons-material/EditCalendarRounded';
+import { styled } from '@mui/material/styles';
+import IconButton from '@mui/material/IconButton';
+
+const StyledButton = styled(IconButton)(({ theme }) => ({
+  borderRadius: theme.shape.borderRadius,
+}));
+const StyledDay = styled(PickersDay)(({ theme }) => ({
+  borderRadius: theme.shape.borderRadius,
+  color:
+    theme.palette.mode === 'light'
+      ? theme.palette.secondary.dark
+      : theme.palette.secondary.light,
+}));
+
+export default function CustomSlots() {
+  return (
+    <LocalizationProvider dateAdapter={AdapterDayjs}>
+      <DemoContainer components={['DatePicker']}>
+        <DatePicker
+          label="Styled picker"
+          slots={{
+            openPickerIcon: EditCalendarRoundedIcon,
+            openPickerButton: StyledButton,
+            day: StyledDay,
+          }}
+          slotProps={{
+            openPickerIcon: { fontSize: 'large' },
+            openPickerButton: { color: 'secondary' },
+            textField: {
+              variant: 'filled',
+              focused: true,
+              color: 'secondary',
+            },
+          }}
+        />
+      </DemoContainer>
+    </LocalizationProvider>
+  );
+}
diff --git a/docs/data/date-pickers/base-concepts/base-concepts.md b/docs/data/date-pickers/base-concepts/base-concepts.md
@@ -174,3 +174,20 @@ const cleanText = (string) =>
 // Example of a test using the helper
 expect(cleanText(input.value)).to.equal('04-17-2022');
 ```
+
+## Overriding slots and slot props
+
+Date and Time Pickers are complex components built using many subcomponents known as **slots**.
+Slots are commonly filled by React components that you can override using the `slots` prop.
+You can also pass additional props to the available slots using the `slotProps` prop.
+Learn more about the mental model of slots in the Base UI documentation: [Overriding component structure](/base-ui/guides/overriding-component-structure/).
+
+You can find the list of available slots for each component in its respective [API reference](/x/api/date-pickers/date-picker/#slots) doc.
+
+Some parts of the Pickers' UI are built on several nested slots. For instance, the adornment of the `TextField` on `DatePicker` contains three slots (`inputAdornment`, `openPickerButton`, and `openPickerIcon`) that you can use depending on what you are trying to customize.
+
+{{"demo": "CustomSlots.js"}}
+
+:::info
+Learn more about overriding slots in the doc page about [Custom slots and subcomponents](/x/react-date-pickers/custom-components/).
+:::
diff --git a/docs/data/date-pickers/custom-components/custom-components.md b/docs/data/date-pickers/custom-components/custom-components.md
@@ -1,19 +1,19 @@
 ---
 productId: x-date-pickers
-title: Date and Time Pickers - Custom subcomponents
-components: DateTimePickerTabs
+title: Date and Time Pickers - Custom slots and subcomponents
+components: DateTimePickerTabs, PickersActionBar, DatePickerToolbar, TimePickerToolbar, DateTimePickerToolbar, PickersCalendarHeader, PickersShortcuts
 ---
 
-# Custom subcomponents
+# Custom slots and subcomponents
 
-<p class="description">The date picker lets you customize subcomponents.</p>
+<p class="description">Learn how to override the default DOM structure of the Date and Time Pickers.</p>
 
 :::info
 The components that can be customized are listed under `slots` section in Date and Time Pickers [API Reference](/x/api/date-pickers/).
 For example, available Date Picker slots can be found [here](/x/api/date-pickers/date-picker/#slots).
 :::
 
-## Overriding components
+## Overriding slot components
 
 You can override the internal elements of the component (known as "slots") using the `slots` prop.
 

diff --git a/docs/data/pages.ts b/docs/data/pages.ts
@@ -328,7 +328,7 @@ const pages: MuiPage[] = [
         children: [
           {
             pathname: '/x/react-date-pickers/custom-components',
-            title: 'Custom subcomponents',
+            title: 'Custom slots and subcomponents',
           },
           { pathname: '/x/react-date-pickers/custom-layout' },
           { pathname: '/x/react-date-pickers/custom-field' },

diff --git a/docs/pages/x/api/date-pickers/date-picker-toolbar.json b/docs/pages/x/api/date-pickers/date-picker-toolbar.json
@@ -26,5 +26,5 @@
   ],
   "styles": { "classes": ["root", "title"], "globalClasses": {}, "name": "MuiDatePickerToolbar" },
   "filename": "/packages/x-date-pickers/src/DatePicker/DatePickerToolbar.tsx",
-  "demos": "<ul></ul>"
+  "demos": "<ul><li><a href=\"/x/react-date-pickers/custom-components/\">Custom slots and subcomponents</a></li></ul>"
 }
diff --git a/docs/pages/x/api/date-pickers/date-time-picker-tabs.json b/docs/pages/x/api/date-pickers/date-time-picker-tabs.json
@@ -29,5 +29,5 @@
   ],
   "styles": { "classes": ["root"], "globalClasses": {}, "name": "MuiDateTimePickerTabs" },
   "filename": "/packages/x-date-pickers/src/DateTimePicker/DateTimePickerTabs.tsx",
-  "demos": "<ul><li><a href=\"/x/react-date-pickers/custom-components/\">Custom subcomponents</a></li></ul>"
+  "demos": "<ul><li><a href=\"/x/react-date-pickers/custom-components/\">Custom slots and subcomponents</a></li></ul>"
 }
diff --git a/docs/pages/x/api/date-pickers/date-time-picker-toolbar.json b/docs/pages/x/api/date-pickers/date-time-picker-toolbar.json
@@ -41,5 +41,5 @@
     "name": "MuiDateTimePickerToolbar"
   },
   "filename": "/packages/x-date-pickers/src/DateTimePicker/DateTimePickerToolbar.tsx",
-  "demos": "<ul></ul>"
+  "demos": "<ul><li><a href=\"/x/react-date-pickers/custom-components/\">Custom slots and subcomponents</a></li></ul>"
 }
diff --git a/docs/pages/x/api/date-pickers/pickers-action-bar.json b/docs/pages/x/api/date-pickers/pickers-action-bar.json
@@ -26,5 +26,5 @@
   "styles": { "classes": ["root", "spacing"], "globalClasses": {}, "name": "MuiPickersActionBar" },
   "filename": "/packages/x-date-pickers/src/PickersActionBar/PickersActionBar.tsx",
   "inheritance": null,
-  "demos": "<ul><li><a href=\"/x/react-date-pickers/custom-layout/\">Custom layout</a></li></ul>"
+  "demos": "<ul><li><a href=\"/x/react-date-pickers/custom-components/\">Custom slots and subcomponents</a></li>\n<li><a href=\"/x/react-date-pickers/custom-layout/\">Custom layout</a></li></ul>"
 }
diff --git a/docs/pages/x/api/date-pickers/pickers-calendar-header.json b/docs/pages/x/api/date-pickers/pickers-calendar-header.json
@@ -25,5 +25,5 @@
     "name": "MuiPickersCalendarHeader"
   },
   "filename": "/packages/x-date-pickers/src/PickersCalendarHeader/PickersCalendarHeader.tsx",
-  "demos": "<ul></ul>"
+  "demos": "<ul><li><a href=\"/x/react-date-pickers/custom-components/\">Custom slots and subcomponents</a></li></ul>"
 }
diff --git a/docs/pages/x/api/date-pickers/pickers-shortcuts.json b/docs/pages/x/api/date-pickers/pickers-shortcuts.json
@@ -35,5 +35,5 @@
     "name": "MuiPickersShortcuts"
   },
   "filename": "/packages/x-date-pickers/src/PickersShortcuts/PickersShortcuts.tsx",
-  "demos": "<ul><li><a href=\"/x/react-date-pickers/shortcuts/\">Shortcuts</a></li></ul>"
+  "demos": "<ul><li><a href=\"/x/react-date-pickers/custom-components/\">Custom slots and subcomponents</a></li>\n<li><a href=\"/x/react-date-pickers/shortcuts/\">Shortcuts</a></li></ul>"
 }
diff --git a/docs/pages/x/api/date-pickers/time-picker-toolbar.json b/docs/pages/x/api/date-pickers/time-picker-toolbar.json
@@ -39,5 +39,5 @@
     "name": "MuiTimePickerToolbar"
   },
   "filename": "/packages/x-date-pickers/src/TimePicker/TimePickerToolbar.tsx",
-  "demos": "<ul></ul>"
+  "demos": "<ul><li><a href=\"/x/react-date-pickers/custom-components/\">Custom slots and subcomponents</a></li></ul>"
 }