From aeef0e2f4356879d3905014002be058f4d1f6494 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Wed, 2 Nov 2022 12:38:30 -0500
Subject: [PATCH 01/25] create base page

---
 .../customization/customization.md            | 10 +--
 docs/data/base/getting-started/usage/usage.md | 78 ------------------
 .../overriding-component-structure.md         | 81 +++++++++++++++++++
 docs/data/base/pages.ts                       |  4 +
 .../guides/overriding-component-structure.js  |  7 ++
 5 files changed, 97 insertions(+), 83 deletions(-)
 create mode 100644 docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
 create mode 100644 docs/pages/base/guides/overriding-component-structure.js

diff --git a/docs/data/base/getting-started/customization/customization.md b/docs/data/base/getting-started/customization/customization.md
index 9de2bf02c97d69..b0d12e7d50c203 100644
--- a/docs/data/base/getting-started/customization/customization.md
+++ b/docs/data/base/getting-started/customization/customization.md
@@ -4,7 +4,7 @@
 
 With MUI Base, you have the freedom to decide how much you want to customize a component's structure and style.
 
-This document reviews the three levels of customization that are available: applying custom CSS rules, overriding default subcomponent slots, and using hooks to build fully custom components.
+This document reviews the three levels of customization that are available: applying custom CSS rules, overriding the default component structure, and using hooks to build fully custom components.
 
 ## Applying custom CSS rules
 
@@ -19,11 +19,11 @@ Additionally, you can import a `[componentName]Classes` object that describes al
 
 {{"demo": "StylingCustomCss.js", "defaultCodeOpen": true}}
 
-## Overriding subcomponent slots
+## Overriding the default structure
 
-If you want to make changes to a component's rendered HTML structure, you can override the default subcomponents ("slots") using the `slots` and/or `component` prop—see ["Shared props" on the Base Usage page](/base/getting-started/usage/#shared-props) for more details.
+If you want to make changes to a component's rendered HTML structure, you can override the default subcomponents ("slots") using the `slots` and/or `component` prop—see the guide on [Overriding component structure](/base/guides/overriding-component-structure/) for more details.
 
-The following demo uses [SwitchUnstyled](/base/react-switch/) to show how to create a styled component by applying styles to three of its subcomponent slots: `root`, `thumb`, and `input`.
+The following demo uses the [Unstyled Switch](/base/react-switch/) to show how to create a styled component by applying styles to three of its subcomponent slots: `root`, `thumb`, and `input`.
 
 Note that although this demo uses [MUI System](/system/styled/) as a styling solution, you are free to choose any alternative.
 
@@ -61,7 +61,7 @@ See ["Components vs. hooks" on the Base Usage page](/base/getting-started/usage/
 
 Hooks return the current state of the component (e.g. `checked`, `disabled`, `open`, etc.) and provide functions that return props you can apply to your fully custom components.
 
-In the case of [SwitchUnstyled](/base/react-switch/), the component is accompanied by the `useSwitch` hook which gives you all of the functionality without any structure.
+In the case of the [Unstyled Switch](/base/react-switch/), the component is accompanied by the `useSwitch` hook which gives you all of the functionality without any structure.
 
 It returns the following object:
 
diff --git a/docs/data/base/getting-started/usage/usage.md b/docs/data/base/getting-started/usage/usage.md
index 8b3709956e3d57..984bf322a6aa81 100644
--- a/docs/data/base/getting-started/usage/usage.md
+++ b/docs/data/base/getting-started/usage/usage.md
@@ -34,84 +34,6 @@ To ensure proper rendering and touch zooming for all devices, add the responsive
 <meta name="viewport" content="initial-scale=1, width=device-width" />
 ```
 
-## Shared props
-
-Base components are self-supporting and fully functional in isolation.
-
-Each component has its own unique API, but all _non-utility_ components accept the following shared props:
-
-### slots
-
-The `slots` prop is an object that lets you override any interior subcomponents—known as **slots**—of the base component itself.
-
-:::info
-Each component contains a root slot, and other appropriate slots based on the nature of the component.
-For example, the Unstyled Badge contains two slots:
-
-- `root`: the container element that wraps the children.
-- `badge`: the badge element itself.
-  :::
-
-You can use the `slots` prop to override default slots with either custom components or HTML elements.
-
-For example, the Unstyled Badge component renders a `<span>` by default.
-The code snippet below shows how to override this by assigning a `<div>` to the root slot:
-
-```jsx
-<BadgeUnstyled slots={{ root: 'div' }} />
-```
-
-### component
-
-The `component` prop provides a shortcut to `slots.root`.
-This is useful if you are only overriding the root element of the component.
-
-The code snippet below shows how to override the root element of the Unstyled Badge component using the `component` prop:
-
-```jsx
-<BadgeUnstyled component="div" />
-```
-
-:::warning
-If the root slot is customized with both the `component` and `slots` props, then `component` will take precedence.
-:::
-
-### slotProps
-
-The `slotProps` prop is an object that contains the props for all slots within a component.
-You can use it to define additional custom props for a component's interior elements.
-
-For example, the code snippet below shows how to add a custom CSS class to the badge slot of the Unstyled Badge component:
-
-```jsx
-<BadgeUnstyled slotProps={{ badge: { className: 'my-badge' } }} />
-```
-
-All additional props placed on the primary component are also propagated into the root slot (just as if they were placed in `slotProps.root`).
-
-These two examples are equivalent:
-
-```jsx
-<BadgeUnstyled id="badge1">
-```
-
-```jsx
-<BadgeUnstyled slotProps={{ root: { id: 'badge1' } }}>
-```
-
-:::warning
-If both `slotProps.root` and additional props have the same keys but different values, the `slotProps.root` props will take precedence.
-This does not apply to classes or the `style` prop—they will be merged instead.
-:::
-
-### Best practices
-
-If you are customizing a component like the [Unstyled Button](/base/react-button/) that only has a root slot, you may prefer to use the more succinct `component` prop instead of `slots`.
-
-Overriding with `component` lets you apply the attributes of that element directly to the root.
-For instance, if you replace the Unstyled Button root with an `<li>` tag, you can add the `<li>` attribute `value` directly to the component.
-If you did the same with `slots.root`, you would need to place this attribute on the `slotProps.root` object in order to avoid a TypeScript error.
-
 ## Components vs. hooks
 
 MUI Base includes two kinds of building blocks: **components** and **hooks**.
diff --git a/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
new file mode 100644
index 00000000000000..812a0b130d95cd
--- /dev/null
+++ b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
@@ -0,0 +1,81 @@
+# Overriding component structure
+
+<p class="description">Overriding component structure.</p>
+
+## Shared props
+
+Base components are self-supporting and fully functional in isolation.
+
+Each component has its own unique API, but all _non-utility_ components accept the following shared props:
+
+### slots
+
+The `slots` prop is an object that lets you override any interior subcomponents—known as **slots**—of the base component itself.
+
+:::info
+Each component contains a root slot, and other appropriate slots based on the nature of the component.
+For example, the Unstyled Badge contains two slots:
+
+- `root`: the container element that wraps the children.
+- `badge`: the badge element itself.
+  :::
+
+You can use the `slots` prop to override default slots with either custom components or HTML elements.
+
+For example, the Unstyled Badge component renders a `<span>` by default.
+The code snippet below shows how to override this by assigning a `<div>` to the root slot:
+
+```jsx
+<BadgeUnstyled slots={{ root: 'div' }} />
+```
+
+### component
+
+The `component` prop provides a shortcut to `slots.root`.
+This is useful if you are only overriding the root element of the component.
+
+The code snippet below shows how to override the root element of the Unstyled Badge component using the `component` prop:
+
+```jsx
+<BadgeUnstyled component="div" />
+```
+
+:::warning
+If the root slot is customized with both the `component` and `slots` props, then `component` will take precedence.
+:::
+
+### slotProps
+
+The `slotProps` prop is an object that contains the props for all slots within a component.
+You can use it to define additional custom props for a component's interior elements.
+
+For example, the code snippet below shows how to add a custom CSS class to the badge slot of the Unstyled Badge component:
+
+```jsx
+<BadgeUnstyled slotProps={{ badge: { className: 'my-badge' } }} />
+```
+
+All additional props placed on the primary component are also propagated into the root slot (just as if they were placed in `slotProps.root`).
+
+These two examples are equivalent:
+
+```jsx
+<BadgeUnstyled id="badge1">
+```
+
+```jsx
+<BadgeUnstyled slotProps={{ root: { id: 'badge1' } }}>
+```
+
+:::warning
+If both `slotProps.root` and additional props have the same keys but different values, the `slotProps.root` props will take precedence.
+This does not apply to classes or the `style` prop—they will be merged instead.
+:::
+
+### Best practices
+
+If you are customizing a component like the [Unstyled Button](/base/react-button/) that only has a root slot, you may prefer to use the more succinct `component` prop instead of `slots`.
+
+Overriding with `component` lets you apply the attributes of that element directly to the root.
+For instance, if you replace the Unstyled Button root with an `<li>` tag, you can add the `<li>` attribute `value` directly to the component.
+If you did the same with `slots.root`, you would need to place this attribute on the `slotProps.root` object in order to avoid a TypeScript error.
diff --git a/docs/data/base/pages.ts b/docs/data/base/pages.ts
index 686b29f4b82b76..d2806f5e76e2d8 100644
--- a/docs/data/base/pages.ts
+++ b/docs/data/base/pages.ts
@@ -87,6 +87,10 @@ const pages = [
         pathname: '/base/guides/working-with-tailwind-css',
         title: 'Working with Tailwind CSS',
       },
+      {
+        pathname: '/base/guides/overriding-component-structure',
+        title: 'Overriding component structure',
+      },
     ],
   },
 ];
diff --git a/docs/pages/base/guides/overriding-component-structure.js b/docs/pages/base/guides/overriding-component-structure.js
new file mode 100644
index 00000000000000..5a1ea2d8c934f1
--- /dev/null
+++ b/docs/pages/base/guides/overriding-component-structure.js
@@ -0,0 +1,7 @@
+import * as React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import * as pageProps from 'docs/data/base/guides/overriding-component-structure/overriding-component-structure.md?@mui/markdown';
+
+export default function Page() {
+  return <MarkdownDocs {...pageProps} />;
+}

From e5bb57b745a70ab909b7df366b4ca594582e42bf Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Wed, 2 Nov 2022 13:53:48 -0500
Subject: [PATCH 02/25] base doc first pass

---
 .../overriding-component-structure.md         | 80 ++++++++++++-------
 1 file changed, 52 insertions(+), 28 deletions(-)

diff --git a/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
index 812a0b130d95cd..ab13f6e50311d4 100644
--- a/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
+++ b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
@@ -2,61 +2,82 @@
 
 <p class="description">Overriding component structure.</p>
 
-## Shared props
+All _non-utility_ MUI Base components accept two props for overriding their rendered HTML structure:
 
-Base components are self-supporting and fully functional in isolation.
+- `component`—to override the root slot
+- `slots`—to override any interior slots (when present)
 
-Each component has its own unique API, but all _non-utility_ components accept the following shared props:
+Additionally, you can pass custom props to interior slots using `slotProps`.
 
-### slots
+## The root slot
 
-The `slots` prop is an object that lets you override any interior subcomponents—known as **slots**—of the base component itself.
+The root slot represents the component's "primary" element.
+For simpler components, the root slot is often filled by the native HTML element the component is intended to replace.
+
+For example, the [Unstyled Button's](/base/react-button/) root slot is a `<button>` element.
+Such components may only have a root; more complex components may have additional [interior slots](#interior-slots).
+
+### The component prop
+
+Use the `component` prop to override a component's root slot.
+The example below shows how to replace the Unstyled Button's `<button>` tag with a `<div>`:
+
+```jsx
+<ButtonUnstyled component="div" />
+```
 
 :::info
-Each component contains a root slot, and other appropriate slots based on the nature of the component.
-For example, the Unstyled Badge contains two slots:
+If you provide a non-interactive element such as a `<span>`, the Unstyled Button component will automatically add the necessary accessibility attributes.
+:::
+
+## Interior slots
+
+Complex components are composed of one or more interior slots in addition to the root.
+These slots are often (but not necessarily) nested within the root.
 
-- `root`: the container element that wraps the children.
-- `badge`: the badge element itself.
-  :::
+For example, the [Unstyled Slider](/base/react-slider/) is composed of a root `<span>` that houses several interior slots named for the elements they represent: track, thumb, rail, and so on.
 
-You can use the `slots` prop to override default slots with either custom components or HTML elements.
+### The slots prop
 
-For example, the Unstyled Badge component renders a `<span>` by default.
-The code snippet below shows how to override this by assigning a `<div>` to the root slot:
+Use the `slots` prop to override a component's interior slots.
+The example below shows how to override the listbox slot in the [Unstyled Select](/base/react-select/) component—a `<ul>` by default—with an `<ol>`:
 
 ```jsx
-<BadgeUnstyled slots={{ root: 'div' }} />
+<SelectUnstyled slots={{ listbox: 'ol' }} />
 ```
 
-### component
+Note that you can also use the `slots` prop to override the root slot:
 
-The `component` prop provides a shortcut to `slots.root`.
-This is useful if you are only overriding the root element of the component.
+```jsx
+// This:
+<SelectUnstyled slots={{ root: 'span' }} />
+
+// ...is the same as this:
+<SelectUnstyled component="span">
+```
 
-The code snippet below shows how to override the root element of the Unstyled Badge component using the `component` prop:
+But if you try to override the root slot with both `component` and `slots`, then `component` will take precedence:
 
 ```jsx
-<BadgeUnstyled component="div" />
-```
+// This:
+<SelectUnstyled component="div" slots={{ root: 'span' }} />
 
-:::warning
-If the root slot is customized with both the `component` and `slots` props, then `component` will take precedence.
-:::
+// ...renders as this:
+<div class="MuiSelectUnstyled-root" />
+```
 
-### slotProps
+### The slotProps prop
 
 The `slotProps` prop is an object that contains the props for all slots within a component.
-You can use it to define additional custom props for a component's interior elements.
+You can use it to define additional custom props to pass to a component's interior slots.
 
-For example, the code snippet below shows how to add a custom CSS class to the badge slot of the Unstyled Badge component:
+For example, the code snippet below shows how to add a custom CSS class to the badge slot of the [Unstyled Badge](/base/react-badge/) component:
 
 ```jsx
 <BadgeUnstyled slotProps={{ badge: { className: 'my-badge' } }} />
 ```
 
 All additional props placed on the primary component are also propagated into the root slot (just as if they were placed in `slotProps.root`).
-
 These two examples are equivalent:
 
 ```jsx
@@ -74,8 +95,11 @@ This does not apply to classes or the `style` prop—they will be merged instead
 
 ### Best practices
 
-If you are customizing a component like the [Unstyled Button](/base/react-button/) that only has a root slot, you may prefer to use the more succinct `component` prop instead of `slots`.
+If you are customizing a simpler component like the Unstyled Button that only has a root slot, you may prefer to use the more succinct `component` prop instead of `slots`.
 
 Overriding with `component` lets you apply the attributes of that element directly to the root.
 For instance, if you replace the Unstyled Button root with an `<li>` tag, you can add the `<li>` attribute `value` directly to the component.
 If you did the same with `slots.root`, you would need to place this attribute on the `slotProps.root` object in order to avoid a TypeScript error.
+
+Be mindful of your rendered DOM structure when overriding the slots of more complex components.
+You can easily break the rules of semantic and accessible HTML if you deviate too far from the default structure—for instance, by unintentionally nesting block-level elements inside of inline elements.

From a08359e7a0833b05e06e9703f7148558023464cf Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Wed, 2 Nov 2022 13:56:28 -0500
Subject: [PATCH 03/25] copy tweak

---
 .../overriding-component-structure.md                       | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
index ab13f6e50311d4..249a87db5e65cd 100644
--- a/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
+++ b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
@@ -1,6 +1,8 @@
 # Overriding component structure
 
-<p class="description">Overriding component structure.</p>
+<p class="description">Learn how to override the default DOM structure of MUI Base components.</p>
+
+
 
 All _non-utility_ MUI Base components accept two props for overriding their rendered HTML structure:
 
@@ -12,7 +14,7 @@ Additionally, you can pass custom props to interior slots using `slotProps`.
 ## The root slot
 
 The root slot represents the component's "primary" element.
-For simpler components, the root slot is often filled by the native HTML element the component is intended to replace.
+For simpler components, the root slot is often filled by the native HTML element that the component is intended to replace.
 
 For example, the [Unstyled Button's](/base/react-button/) root slot is a `<button>` element.
 Such components may only have a root; more complex components may have additional [interior slots](#interior-slots).

From 827a970c479567ced9c7f0e2b395f87f1b5cdc21 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Wed, 2 Nov 2022 14:24:48 -0500
Subject: [PATCH 04/25] base second pass

---
 .../overriding-component-structure.md           | 17 +++++++++++++----
 .../overriding-component-structure.md           |  0
 2 files changed, 13 insertions(+), 4 deletions(-)
 create mode 100644 docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md

diff --git a/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
index 249a87db5e65cd..e8414bded8f4de 100644
--- a/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
+++ b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
@@ -2,12 +2,21 @@
 
 <p class="description">Learn how to override the default DOM structure of MUI Base components.</p>
 
+MUI Base components are designed to suit the widest possible range of use cases, but you many occasionally need to change how a component's structure is rendered in the DOM.
 
+To understand how to do this, it helps to have an accurate mental model of MUI Base components.
+
+## The mental model
+
+A component's structure is determined by the elements that fill that component's **slots**.
+Slots are most commonly filled by HTML tags, but may also be filled by React components.
+
+All components contain a root slot that defines their primary node in the DOM tree; more complex components also contain additional interior slots named after the elements they represent.
 
 All _non-utility_ MUI Base components accept two props for overriding their rendered HTML structure:
 
 - `component`—to override the root slot
-- `slots`—to override any interior slots (when present)
+- `slots`—to override any interior slots (when present) as well as the root
 
 Additionally, you can pass custom props to interior slots using `slotProps`.
 
@@ -17,7 +26,7 @@ The root slot represents the component's "primary" element.
 For simpler components, the root slot is often filled by the native HTML element that the component is intended to replace.
 
 For example, the [Unstyled Button's](/base/react-button/) root slot is a `<button>` element.
-Such components may only have a root; more complex components may have additional [interior slots](#interior-slots).
+This component _only_ has a root slot; more complex components may have additional [interior slots](#interior-slots).
 
 ### The component prop
 
@@ -29,7 +38,7 @@ The example below shows how to replace the Unstyled Button's `<button>` tag with
 ```
 
 :::info
-If you provide a non-interactive element such as a `<span>`, the Unstyled Button component will automatically add the necessary accessibility attributes.
+If you provide a non-interactive element such as a `<span>`, the Unstyled Button will automatically add the necessary accessibility attributes.
 :::
 
 ## Interior slots
@@ -95,7 +104,7 @@ If both `slotProps.root` and additional props have the same keys but different v
 This does not apply to classes or the `style` prop—they will be merged instead.
 :::
 
-### Best practices
+## Best practices
 
 If you are customizing a simpler component like the Unstyled Button that only has a root slot, you may prefer to use the more succinct `component` prop instead of `slots`.
 
diff --git a/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
new file mode 100644
index 00000000000000..e69de29bb2d1d6

From e435faa1e8ce25483c985b3f588fec482885e602 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Wed, 2 Nov 2022 14:43:09 -0500
Subject: [PATCH 05/25] joy doc

---
 .../overriding-component-structure.md         | 120 ++++++++++++++++++
 docs/data/joy/pages.ts                        |   4 +
 .../guides/overriding-component-structure.js  |   7 +
 3 files changed, 131 insertions(+)
 create mode 100644 docs/pages/joy-ui/guides/overriding-component-structure.js

diff --git a/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
index e69de29bb2d1d6..0b7c6113a96572 100644
--- a/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
+++ b/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
@@ -0,0 +1,120 @@
+# Overriding component structure
+
+<p class="description">Learn how to override the default DOM structure of Joy UI components.</p>
+
+Joy UI components are designed to suit the widest possible range of use cases, but you many occasionally need to change how a component's structure is rendered in the DOM.
+
+To understand how to do this, it helps to have an accurate mental model of Joy UI components.
+
+## The mental model
+
+A component's structure is determined by the elements that fill that component's **slots**.
+Slots are most commonly filled by HTML tags, but may also be filled by React components.
+
+All components contain a root slot that defines their primary node in the DOM tree; more complex components also contain additional interior slots named after the elements they represent.
+
+All _non-utility_ Joy UI components accept two props for overriding their rendered HTML structure:
+
+- `component`—to override the root slot
+- `components`—to override any interior slots (when present) as well as the root
+
+Additionally, you can pass custom props to interior slots using `componentsProps`.
+
+## The root slot
+
+The root slot represents the component's "primary" element.
+For simpler components, the root slot is often filled by the native HTML element that the component is intended to replace.
+
+For example, the [Button's](/joy-ui/react-button/) root slot is a `<button>` element.
+This component _only_ has a root slot; more complex components may have additional [interior slots](#interior-slots).
+
+### The component prop
+
+Use the `component` prop to override a component's root slot.
+The example below shows how to replace the Button's `<button>` tag with a `<div>`:
+
+```jsx
+<Button component="div" />
+```
+
+:::info
+If you provide a non-interactive element such as a `<span>`, the Button will automatically add the necessary accessibility attributes.
+:::
+
+## Interior slots
+
+Complex components are composed of one or more interior slots in addition to the root.
+These slots are often (but not necessarily) nested within the root.
+
+For example, the [Slider](/joy-ui/react-slider/) is composed of a root `<span>` that houses several interior slots named for the elements they represent: track, thumb, rail, and so on.
+
+### The components prop
+
+Use the (plural) `components` prop to override a component's interior slots.
+The example below shows how to override the listbox slot in the [Select](/joy-ui/react-select/) component—a `<ul>` by default—with an `<ol>`:
+
+```jsx
+<Select components={{ Listbox: 'ol' }} />
+```
+
+Note that you can also use the `components` prop to override the root slot:
+
+```jsx
+// This:
+<Select components={{ Root: 'span' }} />
+
+// ...is the same as this:
+<Select component="span">
+```
+
+But if you try to override the root slot with both `component` and `components`, then `component` will take precedence:
+
+```jsx
+// This:
+<Select component="div" components={{ root: 'span' }} />
+
+// ...renders as this:
+<div class="MuiSelectUnstyled-root" />
+```
+
+### The componentsProps prop
+
+The `componentsProps` prop is an object that contains the props for all slots within a component.
+You can use it to define additional custom props to pass to a component's interior slots.
+
+For example, the code snippet below shows how to add a custom CSS class to the badge slot of the [Badge](/joy-ui/react-badge/) component:
+
+```jsx
+<Badge componentsProps={{ badge: { className: 'my-badge' } }} />
+```
+
+:::warning
+Slot names must be capitalized for the `components` prop, but lowercase for `componentsProps`.
+:::
+
+All additional props placed on the primary component are also propagated into the root slot (just as if they were placed in `componentsProps.root`).
+These two examples are equivalent:
+
+```jsx
+<Badge id="badge1">
+```
+
+```jsx
+<Badge componentsProps={{ root: { id: 'badge1' } }}>
+```
+
+:::warning
+If both `componentsProps.root` and additional props have the same keys but different values, the `componentsProps.root` props will take precedence.
+This does not apply to classes or the `style` prop—they will be merged instead.
+:::
+
+## Best practices
+
+If you are customizing a simpler component like the Unstyled Button that only has a root slot, you may prefer to use the more succinct `component` prop instead of `components`.
+
+Overriding with `component` lets you apply the attributes of that element directly to the root.
+For instance, if you replace the Unstyled Button root with an `<li>` tag, you can add the `<li>` attribute `value` directly to the component.
+If you did the same with `components.root`, you would need to place this attribute on the `componentsProps.root` object in order to avoid a TypeScript error.
+
+Be mindful of your rendered DOM structure when overriding the slots of more complex components.
+You can easily break the rules of semantic and accessible HTML if you deviate too far from the default structure—for instance, by unintentionally nesting block-level elements inside of inline elements.
diff --git a/docs/data/joy/pages.ts b/docs/data/joy/pages.ts
index 4b5411897787a7..ed9c69202b5069 100644
--- a/docs/data/joy/pages.ts
+++ b/docs/data/joy/pages.ts
@@ -102,6 +102,10 @@ const pages = [
     icon: 'VisibilityIcon',
     children: [
       { pathname: '/joy-ui/guides/applying-dark-mode', title: 'Applying dark mode' },
+      {
+        pathname: '/joy-ui/guides/overriding-component-structure',
+        title: 'Overriding component structure',
+      },
       {
         pathname: '/joy-ui/guides/using-joy-ui-and-material-ui-together',
         title: 'Joy UI and Material UI together',
diff --git a/docs/pages/joy-ui/guides/overriding-component-structure.js b/docs/pages/joy-ui/guides/overriding-component-structure.js
new file mode 100644
index 00000000000000..58a7bb4196fd28
--- /dev/null
+++ b/docs/pages/joy-ui/guides/overriding-component-structure.js
@@ -0,0 +1,7 @@
+import * as React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import * as pageProps from 'docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md?@mui/markdown';
+
+export default function Page() {
+  return <MarkdownDocs {...pageProps} />;
+}

From 6d06a8b5f5f2b5cd0acd8b6b61babee859ff6ae1 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Wed, 2 Nov 2022 15:22:42 -0500
Subject: [PATCH 06/25] noninteractive element clarity

---
 .../overriding-component-structure.md                           | 2 +-
 .../overriding-component-structure.md                           | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
index e8414bded8f4de..d1d56edc8c9460 100644
--- a/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
+++ b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
@@ -38,7 +38,7 @@ The example below shows how to replace the Unstyled Button's `<button>` tag with
 ```
 
 :::info
-If you provide a non-interactive element such as a `<span>`, the Unstyled Button will automatically add the necessary accessibility attributes.
+If you provide a non-interactive element like a `<div>` or a `<span>`, the Button will automatically add the necessary accessibility attributes.
 :::
 
 ## Interior slots
diff --git a/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
index 0b7c6113a96572..54bb59a81f4e2b 100644
--- a/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
+++ b/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
@@ -38,7 +38,7 @@ The example below shows how to replace the Button's `<button>` tag with a `<div>
 ```
 
 :::info
-If you provide a non-interactive element such as a `<span>`, the Button will automatically add the necessary accessibility attributes.
+If you provide a non-interactive element like a `<div>` or a `<span>`, the Button will automatically add the necessary accessibility attributes.
 :::
 
 ## Interior slots

From 435b29efdcd753e1f1fe65dd4918378cf8eb197b Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Wed, 2 Nov 2022 15:34:00 -0500
Subject: [PATCH 07/25] i18n

---
 docs/translations/translations.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/translations/translations.json b/docs/translations/translations.json
index e40279df408a47..7e13f06fcfcf1d 100644
--- a/docs/translations/translations.json
+++ b/docs/translations/translations.json
@@ -219,6 +219,7 @@
     "/base/react-textarea-autosize": "Textarea Autosize",
     "/base/guides": "How To Guides",
     "/base/guides/working-with-tailwind-css": "Working with Tailwind CSS",
+    "/base/guides/overriding-component-structure": "Overriding component structure",
     "/material-ui/getting-started": "Getting started",
     "/material-ui/getting-started/overview": "Overview",
     "/material-ui/getting-started/installation": "Installation",

From 9c64ee0370d47c1418c3dcc20cc4ec708fb377d6 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Wed, 2 Nov 2022 16:34:21 -0500
Subject: [PATCH 08/25] may not many

---
 .../overriding-component-structure.md                           | 2 +-
 .../overriding-component-structure.md                           | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
index d1d56edc8c9460..6121d835ebe867 100644
--- a/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
+++ b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
@@ -2,7 +2,7 @@
 
 <p class="description">Learn how to override the default DOM structure of MUI Base components.</p>
 
-MUI Base components are designed to suit the widest possible range of use cases, but you many occasionally need to change how a component's structure is rendered in the DOM.
+MUI Base components are designed to suit the widest possible range of use cases, but you may occasionally need to change how a component's structure is rendered in the DOM.
 
 To understand how to do this, it helps to have an accurate mental model of MUI Base components.
 
diff --git a/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
index 54bb59a81f4e2b..7eb2a325d5736d 100644
--- a/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
+++ b/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
@@ -2,7 +2,7 @@
 
 <p class="description">Learn how to override the default DOM structure of Joy UI components.</p>
 
-Joy UI components are designed to suit the widest possible range of use cases, but you many occasionally need to change how a component's structure is rendered in the DOM.
+Joy UI components are designed to suit the widest possible range of use cases, but you may occasionally need to change how a component's structure is rendered in the DOM.
 
 To understand how to do this, it helps to have an accurate mental model of Joy UI components.
 

From 9bb173163aa71336d56970dd49130c75d900b497 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Wed, 9 Nov 2022 13:17:04 -0600
Subject: [PATCH 09/25] slots and slotprops for joy

---
 .../overriding-component-structure.md         | 41 +++++++++----------
 1 file changed, 19 insertions(+), 22 deletions(-)

diff --git a/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
index 7eb2a325d5736d..fc4cfc425dbfa1 100644
--- a/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
+++ b/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
@@ -16,9 +16,9 @@ All components contain a root slot that defines their primary node in the DOM tr
 All _non-utility_ Joy UI components accept two props for overriding their rendered HTML structure:
 
 - `component`—to override the root slot
-- `components`—to override any interior slots (when present) as well as the root
+- `slots`—to override any interior slots (when present) as well as the root
 
-Additionally, you can pass custom props to interior slots using `componentsProps`.
+Additionally, you can pass custom props to interior slots using `slotProps`.
 
 ## The root slot
 
@@ -48,51 +48,47 @@ These slots are often (but not necessarily) nested within the root.
 
 For example, the [Slider](/joy-ui/react-slider/) is composed of a root `<span>` that houses several interior slots named for the elements they represent: track, thumb, rail, and so on.
 
-### The components prop
+### The slots prop
 
-Use the (plural) `components` prop to override a component's interior slots.
+Use the `slots` prop to override a component's interior slots.
 The example below shows how to override the listbox slot in the [Select](/joy-ui/react-select/) component—a `<ul>` by default—with an `<ol>`:
 
 ```jsx
-<Select components={{ Listbox: 'ol' }} />
+<Select slots={{ listbox: 'ol' }} />
 ```
 
-Note that you can also use the `components` prop to override the root slot:
+Note that you can also use the `slots` prop to override the root slot:
 
 ```jsx
 // This:
-<Select components={{ Root: 'span' }} />
+<Select slots={{ Root: 'span' }} />
 
 // ...is the same as this:
-<Select component="span">
+<Select slots="span">
 ```
 
-But if you try to override the root slot with both `component` and `components`, then `component` will take precedence:
+But if you try to override the root slot with both `component` and `slots`, then `component` will take precedence:
 
 ```jsx
 // This:
-<Select component="div" components={{ root: 'span' }} />
+<Select component="div" slots={{ root: 'span' }} />
 
 // ...renders as this:
 <div class="MuiSelectUnstyled-root" />
 ```
 
-### The componentsProps prop
+### The slotProps prop
 
-The `componentsProps` prop is an object that contains the props for all slots within a component.
+The `slotProps` prop is an object that contains the props for all slots within a component.
 You can use it to define additional custom props to pass to a component's interior slots.
 
 For example, the code snippet below shows how to add a custom CSS class to the badge slot of the [Badge](/joy-ui/react-badge/) component:
 
 ```jsx
-<Badge componentsProps={{ badge: { className: 'my-badge' } }} />
+<Badge slotProps={{ badge: { className: 'my-badge' } }} />
 ```
 
-:::warning
-Slot names must be capitalized for the `components` prop, but lowercase for `componentsProps`.
-:::
-
-All additional props placed on the primary component are also propagated into the root slot (just as if they were placed in `componentsProps.root`).
+All additional props placed on the primary component are also propagated into the root slot (just as if they were placed in `slotProps.root`).
 These two examples are equivalent:
 
 ```jsx
@@ -100,21 +96,22 @@ These two examples are equivalent:
 ```
 
 ```jsx
-<Badge componentsProps={{ root: { id: 'badge1' } }}>
+<Badge slotProps={{ root: { id: 'badge1' } }}>
 ```
 
 :::warning
-If both `componentsProps.root` and additional props have the same keys but different values, the `componentsProps.root` props will take precedence.
+If both `slotProps.root` and additional props have the same keys but different values, the `slotProps.root` props will take precedence.
 This does not apply to classes or the `style` prop—they will be merged instead.
 :::
 
 ## Best practices
 
-If you are customizing a simpler component like the Unstyled Button that only has a root slot, you may prefer to use the more succinct `component` prop instead of `components`.
+If you are customizing a simpler component like the Unstyled Button that only has a root slot, you may prefer to use the more succinct `component` prop instead of `slots`.
 
 Overriding with `component` lets you apply the attributes of that element directly to the root.
 For instance, if you replace the Unstyled Button root with an `<li>` tag, you can add the `<li>` attribute `value` directly to the component.
-If you did the same with `components.root`, you would need to place this attribute on the `componentsProps.root` object in order to avoid a TypeScript error.
+If you did the same with `slots.root`, you would need to place this attribute on the `slotProps.root` object in order to avoid a TypeScript error.
 
 Be mindful of your rendered DOM structure when overriding the slots of more complex components.
 You can easily break the rules of semantic and accessible HTML if you deviate too far from the default structure—for instance, by unintentionally nesting block-level elements inside of inline elements.
+Joy UI components automatically correct semantically incorrect HTML—see [Automatic adjustment](/joy-ui/main-features/automatic-adjustment/) for details.

From 8e399911b4a777c2e2e4a955b99ed6911eeaf16e Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Tue, 29 Nov 2022 19:21:48 -0600
Subject: [PATCH 10/25] component and slots demos

---
 .../OverridingInternalSlot.js                     | 12 ++++++++++++
 .../OverridingInternalSlot.tsx                    | 12 ++++++++++++
 .../OverridingInternalSlot.tsx.preview            |  4 ++++
 .../OverridingRootSlot.js                         |  6 ++++++
 .../OverridingRootSlot.tsx                        |  8 ++++++++
 .../OverridingRootSlot.tsx.preview                |  1 +
 .../overriding-component-structure.md             | 15 ++++++---------
 .../OverridingInternalSlot.js                     | 12 ++++++++++++
 .../OverridingInternalSlot.tsx                    | 12 ++++++++++++
 .../OverridingInternalSlot.tsx.preview            |  4 ++++
 .../OverridingRootSlot.js                         |  6 ++++++
 .../OverridingRootSlot.tsx                        |  8 ++++++++
 .../OverridingRootSlot.tsx.preview                |  1 +
 .../overriding-component-structure.md             | 14 ++++++--------
 14 files changed, 98 insertions(+), 17 deletions(-)
 create mode 100644 docs/data/base/guides/overriding-component-structure/OverridingInternalSlot.js
 create mode 100644 docs/data/base/guides/overriding-component-structure/OverridingInternalSlot.tsx
 create mode 100644 docs/data/base/guides/overriding-component-structure/OverridingInternalSlot.tsx.preview
 create mode 100644 docs/data/base/guides/overriding-component-structure/OverridingRootSlot.js
 create mode 100644 docs/data/base/guides/overriding-component-structure/OverridingRootSlot.tsx
 create mode 100644 docs/data/base/guides/overriding-component-structure/OverridingRootSlot.tsx.preview
 create mode 100644 docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.js
 create mode 100644 docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx
 create mode 100644 docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx.preview
 create mode 100644 docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.js
 create mode 100644 docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx
 create mode 100644 docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx.preview

diff --git a/docs/data/base/guides/overriding-component-structure/OverridingInternalSlot.js b/docs/data/base/guides/overriding-component-structure/OverridingInternalSlot.js
new file mode 100644
index 00000000000000..8f195aea3f1a88
--- /dev/null
+++ b/docs/data/base/guides/overriding-component-structure/OverridingInternalSlot.js
@@ -0,0 +1,12 @@
+import * as React from 'react';
+import SelectUnstyled from '@mui/base/SelectUnstyled';
+import OptionUnstyled from '@mui/base/OptionUnstyled';
+
+export default function OrderedListSelect() {
+  return (
+    <SelectUnstyled slots={{ listbox: 'ol' }} defaultValue="First option">
+      <OptionUnstyled value="First option">First option</OptionUnstyled>
+      <OptionUnstyled value="Second option">Second option</OptionUnstyled>
+    </SelectUnstyled>
+  );
+}
diff --git a/docs/data/base/guides/overriding-component-structure/OverridingInternalSlot.tsx b/docs/data/base/guides/overriding-component-structure/OverridingInternalSlot.tsx
new file mode 100644
index 00000000000000..8f195aea3f1a88
--- /dev/null
+++ b/docs/data/base/guides/overriding-component-structure/OverridingInternalSlot.tsx
@@ -0,0 +1,12 @@
+import * as React from 'react';
+import SelectUnstyled from '@mui/base/SelectUnstyled';
+import OptionUnstyled from '@mui/base/OptionUnstyled';
+
+export default function OrderedListSelect() {
+  return (
+    <SelectUnstyled slots={{ listbox: 'ol' }} defaultValue="First option">
+      <OptionUnstyled value="First option">First option</OptionUnstyled>
+      <OptionUnstyled value="Second option">Second option</OptionUnstyled>
+    </SelectUnstyled>
+  );
+}
diff --git a/docs/data/base/guides/overriding-component-structure/OverridingInternalSlot.tsx.preview b/docs/data/base/guides/overriding-component-structure/OverridingInternalSlot.tsx.preview
new file mode 100644
index 00000000000000..e5d56c16fb0fd8
--- /dev/null
+++ b/docs/data/base/guides/overriding-component-structure/OverridingInternalSlot.tsx.preview
@@ -0,0 +1,4 @@
+<SelectUnstyled slots={{ listbox: 'ol' }} defaultValue="First option">
+  <OptionUnstyled value="First option">First option</OptionUnstyled>
+  <OptionUnstyled value="Second option">Second option</OptionUnstyled>
+</SelectUnstyled>
\ No newline at end of file
diff --git a/docs/data/base/guides/overriding-component-structure/OverridingRootSlot.js b/docs/data/base/guides/overriding-component-structure/OverridingRootSlot.js
new file mode 100644
index 00000000000000..f148067f05e38e
--- /dev/null
+++ b/docs/data/base/guides/overriding-component-structure/OverridingRootSlot.js
@@ -0,0 +1,6 @@
+import * as React from 'react';
+import ButtonUnstyled from '@mui/base/ButtonUnstyled';
+
+export default function DivButton() {
+  return <ButtonUnstyled component="div">Button</ButtonUnstyled>;
+}
diff --git a/docs/data/base/guides/overriding-component-structure/OverridingRootSlot.tsx b/docs/data/base/guides/overriding-component-structure/OverridingRootSlot.tsx
new file mode 100644
index 00000000000000..147549104700f6
--- /dev/null
+++ b/docs/data/base/guides/overriding-component-structure/OverridingRootSlot.tsx
@@ -0,0 +1,8 @@
+import * as React from 'react';
+import ButtonUnstyled from '@mui/base/ButtonUnstyled';
+
+export default function DivButton() {
+  return (
+      <ButtonUnstyled component="div">Button</ButtonUnstyled>
+  );
+}
diff --git a/docs/data/base/guides/overriding-component-structure/OverridingRootSlot.tsx.preview b/docs/data/base/guides/overriding-component-structure/OverridingRootSlot.tsx.preview
new file mode 100644
index 00000000000000..1f24878ebbdc23
--- /dev/null
+++ b/docs/data/base/guides/overriding-component-structure/OverridingRootSlot.tsx.preview
@@ -0,0 +1 @@
+<ButtonUnstyled component="div">Button</ButtonUnstyled>
\ No newline at end of file
diff --git a/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
index 6121d835ebe867..4dc93a71bae582 100644
--- a/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
+++ b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
@@ -4,7 +4,7 @@
 
 MUI Base components are designed to suit the widest possible range of use cases, but you may occasionally need to change how a component's structure is rendered in the DOM.
 
-To understand how to do this, it helps to have an accurate mental model of MUI Base components.
+To understand how to do this, it helps to have an accurate mental model of MUI components.
 
 ## The mental model
 
@@ -31,14 +31,13 @@ This component _only_ has a root slot; more complex components may have addition
 ### The component prop
 
 Use the `component` prop to override a component's root slot.
-The example below shows how to replace the Unstyled Button's `<button>` tag with a `<div>`:
+The demo below shows how to replace the Button's `<button>` tag with a `<div>`:
 
-```jsx
-<ButtonUnstyled component="div" />
-```
+{{"demo": "OverridingRootSlot.js"}}
 
-:::info
+:::success
 If you provide a non-interactive element like a `<div>` or a `<span>`, the Button will automatically add the necessary accessibility attributes.
+Try inspecting the demo Button above in your browser's dev tools to see this feature in action.
 :::
 
 ## Interior slots
@@ -53,9 +52,7 @@ For example, the [Unstyled Slider](/base/react-slider/) is composed of a root `<
 Use the `slots` prop to override a component's interior slots.
 The example below shows how to override the listbox slot in the [Unstyled Select](/base/react-select/) component—a `<ul>` by default—with an `<ol>`:
 
-```jsx
-<SelectUnstyled slots={{ listbox: 'ol' }} />
-```
+{{"demo": "OverridingInternalSlot.js"}}
 
 Note that you can also use the `slots` prop to override the root slot:
 
diff --git a/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.js b/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.js
new file mode 100644
index 00000000000000..ce87cae026fc4e
--- /dev/null
+++ b/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.js
@@ -0,0 +1,12 @@
+import * as React from 'react';
+import Select from '@mui/joy/Select';
+import Option from '@mui/joy/Option';
+
+export default function OrderedListSelect() {
+  return (
+    <Select defaultValue="First option">
+      <Option value="First option">First option</Option>
+      <Option value="Second option">Second option</Option>
+    </Select>
+  );
+}
diff --git a/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx b/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx
new file mode 100644
index 00000000000000..ce87cae026fc4e
--- /dev/null
+++ b/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx
@@ -0,0 +1,12 @@
+import * as React from 'react';
+import Select from '@mui/joy/Select';
+import Option from '@mui/joy/Option';
+
+export default function OrderedListSelect() {
+  return (
+    <Select defaultValue="First option">
+      <Option value="First option">First option</Option>
+      <Option value="Second option">Second option</Option>
+    </Select>
+  );
+}
diff --git a/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx.preview b/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx.preview
new file mode 100644
index 00000000000000..dd453281887a9f
--- /dev/null
+++ b/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx.preview
@@ -0,0 +1,4 @@
+<Select defaultValue="First option">
+  <Option value="First option">First option</Option>
+  <Option value="Second option">Second option</Option>
+</Select>
\ No newline at end of file
diff --git a/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.js b/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.js
new file mode 100644
index 00000000000000..7d715d2347fa71
--- /dev/null
+++ b/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.js
@@ -0,0 +1,6 @@
+import * as React from 'react';
+import Button from '@mui/joy/Button';
+
+export default function DivButton() {
+  return <Button component="div">Button</Button>;
+}
diff --git a/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx b/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx
new file mode 100644
index 00000000000000..623ce7485fd488
--- /dev/null
+++ b/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx
@@ -0,0 +1,8 @@
+import * as React from 'react';
+import Button from '@mui/joy/Button';
+
+export default function DivButton() {
+  return (
+      <Button component="div">Button</Button>
+  );
+}
diff --git a/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx.preview b/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx.preview
new file mode 100644
index 00000000000000..1a3d44bd97a2fa
--- /dev/null
+++ b/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx.preview
@@ -0,0 +1 @@
+<Button component="div">Button</Button>
\ No newline at end of file
diff --git a/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
index fc4cfc425dbfa1..73865901116ff9 100644
--- a/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
+++ b/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
@@ -4,7 +4,7 @@
 
 Joy UI components are designed to suit the widest possible range of use cases, but you may occasionally need to change how a component's structure is rendered in the DOM.
 
-To understand how to do this, it helps to have an accurate mental model of Joy UI components.
+To understand how to do this, it helps to have an accurate mental model of MUI components.
 
 ## The mental model
 
@@ -28,17 +28,17 @@ For simpler components, the root slot is often filled by the native HTML element
 For example, the [Button's](/joy-ui/react-button/) root slot is a `<button>` element.
 This component _only_ has a root slot; more complex components may have additional [interior slots](#interior-slots).
 
+
 ### The component prop
 
 Use the `component` prop to override a component's root slot.
-The example below shows how to replace the Button's `<button>` tag with a `<div>`:
+The demo below shows how to replace the Button's `<button>` tag with a `<div>`:
 
-```jsx
-<Button component="div" />
-```
+{{"demo": "OverridingRootSlot.js"}}
 
 :::info
 If you provide a non-interactive element like a `<div>` or a `<span>`, the Button will automatically add the necessary accessibility attributes.
+Try inspecting the demo Button above in your browser's dev tools to see this feature in action.
 :::
 
 ## Interior slots
@@ -53,9 +53,7 @@ For example, the [Slider](/joy-ui/react-slider/) is composed of a root `<span>`
 Use the `slots` prop to override a component's interior slots.
 The example below shows how to override the listbox slot in the [Select](/joy-ui/react-select/) component—a `<ul>` by default—with an `<ol>`:
 
-```jsx
-<Select slots={{ listbox: 'ol' }} />
-```
+{{"demo": "OverridingInternalSlot.js"}}
 
 Note that you can also use the `slots` prop to override the root slot:
 

From 8e452eef6ae1e644de8764c174c553ca93f71708 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Tue, 29 Nov 2022 19:39:21 -0600
Subject: [PATCH 11/25] progress

---
 .../OverridingRootSlot.tsx                           |  4 +---
 .../OverridingInternalSlot.js                        |  2 +-
 .../OverridingInternalSlot.tsx                       | 12 ------------
 .../OverridingInternalSlot.tsx.preview               |  4 ----
 .../OverridingRootSlot.tsx                           |  4 +---
 .../overriding-component-structure.md                |  1 -
 6 files changed, 3 insertions(+), 24 deletions(-)
 delete mode 100644 docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx
 delete mode 100644 docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx.preview

diff --git a/docs/data/base/guides/overriding-component-structure/OverridingRootSlot.tsx b/docs/data/base/guides/overriding-component-structure/OverridingRootSlot.tsx
index 147549104700f6..f148067f05e38e 100644
--- a/docs/data/base/guides/overriding-component-structure/OverridingRootSlot.tsx
+++ b/docs/data/base/guides/overriding-component-structure/OverridingRootSlot.tsx
@@ -2,7 +2,5 @@ import * as React from 'react';
 import ButtonUnstyled from '@mui/base/ButtonUnstyled';
 
 export default function DivButton() {
-  return (
-      <ButtonUnstyled component="div">Button</ButtonUnstyled>
-  );
+  return <ButtonUnstyled component="div">Button</ButtonUnstyled>;
 }
diff --git a/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.js b/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.js
index ce87cae026fc4e..010382a1e1224e 100644
--- a/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.js
+++ b/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.js
@@ -4,7 +4,7 @@ import Option from '@mui/joy/Option';
 
 export default function OrderedListSelect() {
   return (
-    <Select defaultValue="First option">
+    <Select slots={{ listbox: 'ol' }} defaultValue="First option">
       <Option value="First option">First option</Option>
       <Option value="Second option">Second option</Option>
     </Select>
diff --git a/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx b/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx
deleted file mode 100644
index ce87cae026fc4e..00000000000000
--- a/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx
+++ /dev/null
@@ -1,12 +0,0 @@
-import * as React from 'react';
-import Select from '@mui/joy/Select';
-import Option from '@mui/joy/Option';
-
-export default function OrderedListSelect() {
-  return (
-    <Select defaultValue="First option">
-      <Option value="First option">First option</Option>
-      <Option value="Second option">Second option</Option>
-    </Select>
-  );
-}
diff --git a/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx.preview b/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx.preview
deleted file mode 100644
index dd453281887a9f..00000000000000
--- a/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx.preview
+++ /dev/null
@@ -1,4 +0,0 @@
-<Select defaultValue="First option">
-  <Option value="First option">First option</Option>
-  <Option value="Second option">Second option</Option>
-</Select>
\ No newline at end of file
diff --git a/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx b/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx
index 623ce7485fd488..7d715d2347fa71 100644
--- a/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx
+++ b/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx
@@ -2,7 +2,5 @@ import * as React from 'react';
 import Button from '@mui/joy/Button';
 
 export default function DivButton() {
-  return (
-      <Button component="div">Button</Button>
-  );
+  return <Button component="div">Button</Button>;
 }
diff --git a/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
index 73865901116ff9..3910203fb7248b 100644
--- a/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
+++ b/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
@@ -28,7 +28,6 @@ For simpler components, the root slot is often filled by the native HTML element
 For example, the [Button's](/joy-ui/react-button/) root slot is a `<button>` element.
 This component _only_ has a root slot; more complex components may have additional [interior slots](#interior-slots).
 
-
 ### The component prop
 
 Use the `component` prop to override a component's root slot.

From 092ee3441bb62ec77d5f657a7bdeed34becf4fc4 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Fri, 27 Jan 2023 17:07:32 -0600
Subject: [PATCH 12/25] Update
 docs/data/base/guides/overriding-component-structure/overriding-component-structure.md

Co-authored-by: Siriwat K <siriwatkunaporn@gmail.com>
Signed-off-by: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
---
 .../overriding-component-structure.md                        | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
index 4dc93a71bae582..f329ca585361f8 100644
--- a/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
+++ b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
@@ -103,11 +103,6 @@ This does not apply to classes or the `style` prop—they will be merged instead
 
 ## Best practices
 
-If you are customizing a simpler component like the Unstyled Button that only has a root slot, you may prefer to use the more succinct `component` prop instead of `slots`.
-
-Overriding with `component` lets you apply the attributes of that element directly to the root.
-For instance, if you replace the Unstyled Button root with an `<li>` tag, you can add the `<li>` attribute `value` directly to the component.
-If you did the same with `slots.root`, you would need to place this attribute on the `slotProps.root` object in order to avoid a TypeScript error.
 
 Be mindful of your rendered DOM structure when overriding the slots of more complex components.
 You can easily break the rules of semantic and accessible HTML if you deviate too far from the default structure—for instance, by unintentionally nesting block-level elements inside of inline elements.

From 269638802df9f8dc372733c519d889cfbbe179d0 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Fri, 27 Jan 2023 17:07:42 -0600
Subject: [PATCH 13/25] Update
 docs/data/base/guides/overriding-component-structure/overriding-component-structure.md

Co-authored-by: Siriwat K <siriwatkunaporn@gmail.com>
Signed-off-by: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
---
 .../overriding-component-structure.md                           | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
index f329ca585361f8..d7278ac34f1592 100644
--- a/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
+++ b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
@@ -49,7 +49,7 @@ For example, the [Unstyled Slider](/base/react-slider/) is composed of a root `<
 
 ### The slots prop
 
-Use the `slots` prop to override a component's interior slots.
+Use the `slots` prop to replace a component's interior slots.
 The example below shows how to override the listbox slot in the [Unstyled Select](/base/react-select/) component—a `<ul>` by default—with an `<ol>`:
 
 {{"demo": "OverridingInternalSlot.js"}}

From ced24e63430066db260adea02818164cf0c16baf Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Thu, 9 Mar 2023 11:30:45 +0100
Subject: [PATCH 14/25] outermost

---
 .../overriding-component-structure.md                          | 3 +--
 .../overriding-component-structure.md                          | 2 +-
 2 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
index d7278ac34f1592..3dd51866519bf6 100644
--- a/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
+++ b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
@@ -22,7 +22,7 @@ Additionally, you can pass custom props to interior slots using `slotProps`.
 
 ## The root slot
 
-The root slot represents the component's "primary" element.
+The root slot represents the component's outermost element.
 For simpler components, the root slot is often filled by the native HTML element that the component is intended to replace.
 
 For example, the [Unstyled Button's](/base/react-button/) root slot is a `<button>` element.
@@ -103,6 +103,5 @@ This does not apply to classes or the `style` prop—they will be merged instead
 
 ## Best practices
 
-
 Be mindful of your rendered DOM structure when overriding the slots of more complex components.
 You can easily break the rules of semantic and accessible HTML if you deviate too far from the default structure—for instance, by unintentionally nesting block-level elements inside of inline elements.
diff --git a/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
index 3910203fb7248b..371d0d1e6d5a4a 100644
--- a/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
+++ b/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
@@ -22,7 +22,7 @@ Additionally, you can pass custom props to interior slots using `slotProps`.
 
 ## The root slot
 
-The root slot represents the component's "primary" element.
+The root slot represents the component's outermost element.
 For simpler components, the root slot is often filled by the native HTML element that the component is intended to replace.
 
 For example, the [Button's](/joy-ui/react-button/) root slot is a `<button>` element.

From 59c86ce008b154a7cd9ba9a3ef0140ebd9dc08fb Mon Sep 17 00:00:00 2001
From: siriwatknp <siriwatkunaporn@gmail.com>
Date: Mon, 13 Mar 2023 01:46:41 +0700
Subject: [PATCH 15/25] update content and examples

---
 .../OverridingInternalSlot.js                 | 28 ++++++++---
 .../OverridingInternalSlot.tsx                | 26 ++++++++++
 .../OverridingRootSlot.js                     | 11 ++++-
 .../OverridingRootSlot.tsx                    | 11 ++++-
 .../overriding-component-structure.md         | 48 ++++++-------------
 5 files changed, 81 insertions(+), 43 deletions(-)
 create mode 100644 docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx

diff --git a/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.js b/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.js
index 010382a1e1224e..4c8b3b72c88f61 100644
--- a/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.js
+++ b/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.js
@@ -1,12 +1,26 @@
 import * as React from 'react';
-import Select from '@mui/joy/Select';
-import Option from '@mui/joy/Option';
+import Box from '@mui/joy/Box';
+import Autocomplete from '@mui/joy/Autocomplete';
+import AutocompleteListbox from '@mui/joy/AutocompleteListbox';
 
-export default function OrderedListSelect() {
+export default function OverridingInternalSlot() {
   return (
-    <Select slots={{ listbox: 'ol' }} defaultValue="First option">
-      <Option value="First option">First option</Option>
-      <Option value="Second option">Second option</Option>
-    </Select>
+    <Box sx={{ display: 'flex', flexDirection: 'column', width: 320 }}>
+      <Autocomplete
+        open
+        multiple
+        disableClearable
+        placeholder="Type to search"
+        options={[
+          { label: '🆘 Need help' },
+          { label: '✨ Improvement' },
+          { label: '🚀 New feature' },
+          { label: '🐛 Bug fix' },
+        ]}
+        slots={{
+          listbox: AutocompleteListbox,
+        }}
+      />
+    </Box>
   );
 }
diff --git a/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx b/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx
new file mode 100644
index 00000000000000..4c8b3b72c88f61
--- /dev/null
+++ b/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx
@@ -0,0 +1,26 @@
+import * as React from 'react';
+import Box from '@mui/joy/Box';
+import Autocomplete from '@mui/joy/Autocomplete';
+import AutocompleteListbox from '@mui/joy/AutocompleteListbox';
+
+export default function OverridingInternalSlot() {
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', width: 320 }}>
+      <Autocomplete
+        open
+        multiple
+        disableClearable
+        placeholder="Type to search"
+        options={[
+          { label: '🆘 Need help' },
+          { label: '✨ Improvement' },
+          { label: '🚀 New feature' },
+          { label: '🐛 Bug fix' },
+        ]}
+        slots={{
+          listbox: AutocompleteListbox,
+        }}
+      />
+    </Box>
+  );
+}
diff --git a/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.js b/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.js
index 7d715d2347fa71..d3199709507c20 100644
--- a/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.js
+++ b/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.js
@@ -2,5 +2,14 @@ import * as React from 'react';
 import Button from '@mui/joy/Button';
 
 export default function DivButton() {
-  return <Button component="div">Button</Button>;
+  return (
+    <Button
+      component="a"
+      href="https://mui.com/about-us/"
+      target="_blank"
+      rel="noopener noreferrer"
+    >
+      About us
+    </Button>
+  );
 }
diff --git a/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx b/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx
index 7d715d2347fa71..d3199709507c20 100644
--- a/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx
+++ b/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx
@@ -2,5 +2,14 @@ import * as React from 'react';
 import Button from '@mui/joy/Button';
 
 export default function DivButton() {
-  return <Button component="div">Button</Button>;
+  return (
+    <Button
+      component="a"
+      href="https://mui.com/about-us/"
+      target="_blank"
+      rel="noopener noreferrer"
+    >
+      About us
+    </Button>
+  );
 }
diff --git a/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
index 371d0d1e6d5a4a..667f7f7035295b 100644
--- a/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
+++ b/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
@@ -16,14 +16,13 @@ All components contain a root slot that defines their primary node in the DOM tr
 All _non-utility_ Joy UI components accept two props for overriding their rendered HTML structure:
 
 - `component`—to override the root slot
-- `slots`—to override any interior slots (when present) as well as the root
+- `slots`—to replace any interior slots (when present) as well as the root
 
 Additionally, you can pass custom props to interior slots using `slotProps`.
 
 ## The root slot
 
-The root slot represents the component's outermost element.
-For simpler components, the root slot is often filled by the native HTML element that the component is intended to replace.
+The root slot represents the component's outermost element. It is filled by a styled component with an appropriate HTML element.
 
 For example, the [Button's](/joy-ui/react-button/) root slot is a `<button>` element.
 This component _only_ has a root slot; more complex components may have additional [interior slots](#interior-slots).
@@ -31,13 +30,12 @@ This component _only_ has a root slot; more complex components may have addition
 ### The component prop
 
 Use the `component` prop to override a component's root slot.
-The demo below shows how to replace the Button's `<button>` tag with a `<div>`:
+The demo below shows how to replace the Button's `<button>` tag with a `<a>` to create a link button:
 
 {{"demo": "OverridingRootSlot.js"}}
 
 :::info
-If you provide a non-interactive element like a `<div>` or a `<span>`, the Button will automatically add the necessary accessibility attributes.
-Try inspecting the demo Button above in your browser's dev tools to see this feature in action.
+The props `href`, `target`, and `rel` are specific to `<a>` tag. Be sure to use the appropriate attributes when you provide a custom `component` prop.
 :::
 
 ## Interior slots
@@ -45,55 +43,35 @@ Try inspecting the demo Button above in your browser's dev tools to see this fea
 Complex components are composed of one or more interior slots in addition to the root.
 These slots are often (but not necessarily) nested within the root.
 
-For example, the [Slider](/joy-ui/react-slider/) is composed of a root `<span>` that houses several interior slots named for the elements they represent: track, thumb, rail, and so on.
+For example, the [Autocomplete](/joy-ui/react-autocomplete/) is composed of a root `<div>` that houses several interior slots named for the elements they represent: input, startDecorator, endDecorator, clearIndicator, popupIndicator and so on.
 
 ### The slots prop
 
-Use the `slots` prop to override a component's interior slots.
-The example below shows how to override the listbox slot in the [Select](/joy-ui/react-select/) component—a `<ul>` by default—with an `<ol>`:
+Use the `slots` prop to replace a component's interior slots.
+The example below shows how to replace the listbox slot in the [Autocomplete](/joy-ui/react-autocomplete/) component to remove the popup functionality:
 
 {{"demo": "OverridingInternalSlot.js"}}
 
-Note that you can also use the `slots` prop to override the root slot:
-
-```jsx
-// This:
-<Select slots={{ Root: 'span' }} />
-
-// ...is the same as this:
-<Select slots="span">
-```
-
-But if you try to override the root slot with both `component` and `slots`, then `component` will take precedence:
-
-```jsx
-// This:
-<Select component="div" slots={{ root: 'span' }} />
-
-// ...renders as this:
-<div class="MuiSelectUnstyled-root" />
-```
-
 ### The slotProps prop
 
 The `slotProps` prop is an object that contains the props for all slots within a component.
 You can use it to define additional custom props to pass to a component's interior slots.
 
-For example, the code snippet below shows how to add a custom CSS class to the badge slot of the [Badge](/joy-ui/react-badge/) component:
+For example, the code snippet below shows how to add a custom `data-testid` to the listbox slot of the [Autocomplete](/joy-ui/react-autocomplete/) component:
 
 ```jsx
-<Badge slotProps={{ badge: { className: 'my-badge' } }} />
+<Autocomplete slotProps={{ listbox: { 'data-testid': 'my-listbox' } }} />
 ```
 
 All additional props placed on the primary component are also propagated into the root slot (just as if they were placed in `slotProps.root`).
 These two examples are equivalent:
 
 ```jsx
-<Badge id="badge1">
+<Autocomplete id="badge1">
 ```
 
 ```jsx
-<Badge slotProps={{ root: { id: 'badge1' } }}>
+<Autocomplete slotProps={{ root: { id: 'badge1' } }}>
 ```
 
 :::warning
@@ -103,7 +81,9 @@ This does not apply to classes or the `style` prop—they will be merged instead
 
 ## Best practices
 
-If you are customizing a simpler component like the Unstyled Button that only has a root slot, you may prefer to use the more succinct `component` prop instead of `slots`.
+Use `component` or `slotProps.component` prop to override the element by preserving the styles of the slot.
+
+Use `slots` prop to replace the default styled component for that specific slot.
 
 Overriding with `component` lets you apply the attributes of that element directly to the root.
 For instance, if you replace the Unstyled Button root with an `<li>` tag, you can add the `<li>` attribute `value` directly to the component.

From bbdc59180cf579a8c09750bad630a7c128f3c679 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Wed, 5 Apr 2023 11:53:37 -0500
Subject: [PATCH 16/25] Apply suggestions from code review

Co-authored-by: Siriwat K <siriwatkunaporn@gmail.com>
---
 .../overriding-component-structure.md                         | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
index 667f7f7035295b..2d5392ea0ed053 100644
--- a/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
+++ b/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
@@ -81,9 +81,9 @@ This does not apply to classes or the `style` prop—they will be merged instead
 
 ## Best practices
 
-Use `component` or `slotProps.component` prop to override the element by preserving the styles of the slot.
+Use `component` or `slotProps.{slot}.component` prop to override the element by preserving the styles of the slot.
 
-Use `slots` prop to replace the default styled component for that specific slot.
+Use `slots` prop to replace the slot's styles and functionality with your custom component.
 
 Overriding with `component` lets you apply the attributes of that element directly to the root.
 For instance, if you replace the Unstyled Button root with an `<li>` tag, you can add the `<li>` attribute `value` directly to the component.

From 9e0a93cfe5b9e0e7cb91c5d5c109f28b772d3282 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Wed, 5 Apr 2023 12:07:30 -0500
Subject: [PATCH 17/25] merge conflict

---
 .../customization/customization.md            | 130 +++++++++++++++++-
 1 file changed, 126 insertions(+), 4 deletions(-)

diff --git a/docs/data/base/getting-started/customization/customization.md b/docs/data/base/getting-started/customization/customization.md
index 67e59ba2cd58c5..b55598d415f38f 100644
--- a/docs/data/base/getting-started/customization/customization.md
+++ b/docs/data/base/getting-started/customization/customization.md
@@ -4,9 +4,97 @@
 
 With MUI Base, you have the freedom to decide how much you want to customize a component's structure and style.
 
-This document reviews the three levels of customization that are available: applying custom CSS rules, overriding the default component structure, and using hooks to build fully custom components.
+## Styling the components
 
-## Applying custom CSS rules
+> > > > > > > master
+
+This section reviews several methods of customization that are available: applying custom CSS rules, overriding default subcomponent slots, customizing the slot props, and using hooks to build fully custom components.
+
+### Which option to choose?
+
+The multitude of options can be overwhelming, especially if you're new to MUI Base.
+How to decide which one to use, then?
+
+The first decision to make is whether to use unstyled components or hooks.
+Hooks are better suited for making component libraries that can be further customized.
+For example, our own Joy UI is implemented using hooks from MUI Base.
+Hooks also serve as the basis for several Material UI components, and future versions of the library will use them even more extensively.
+
+If you don't need to make your component library customizable (for instance, by exposing `slotProps`), then the unstyled components may be a better option thanks to their simplicity.
+
+After choosing unstyled components, there is one more decision to make: how to style them.
+The answer depends on the styling solution used in the project:
+
+#### Plain CSS, Sass, Less
+
+...or anything else that compiles to CSS:
+
+You can either [style the components using the built-in classes](#applying-custom-css-rules) or [specify your own classes](#customizing-slot-props) and reference them in your stylesheets.
+
+#### CSS Modules
+
+When working with [CSS Modules](https://github.com/css-modules/css-modules), the simplest approach is to [specify custom classes using `slotProps`](#customizing-slot-props), as shown below:
+
+```tsx
+import clsx from 'clsx';
+import classes from './styles.module.css';
+
+export default function Switch(props) {
+  const slotProps = {
+    root: (ownerState: SwitchUnstyledOwnerState) => ({
+      className: clsx(classes.root, {
+        [classes.checked]: ownerState.checked,
+        [classes.disabled]: ownerState.disabled,
+      }),
+    }),
+    thumb: { className: classes.thumb },
+    track: { className: classes.track },
+    input: { className: classes.input },
+  };
+
+  return <SwitchUnstyled {...props} slotProps={slotProps} />;
+}
+```
+
+In this example we're using the [clsx](https://www.npmjs.com/package/clsx) utility to reduce the effort needed to apply class names conditionally.
+
+#### Tailwind CSS
+
+Use [`slotProps`](#customizing-slot-props) to apply custom styles using [Tailwind CSS](https://www.tailwindcss.com/), as shown below:
+
+```tsx
+export default function Switch(props) {
+  const slotProps = {
+    root: (ownerState: SwitchUnstyledOwnerState) => ({
+      className: `inline-block w-8 h-5 rounded-full cursor-pointer relative ${
+        ownerState.checked ? 'bg-cyan-500' : 'bg-zinc-400'
+      }`,
+    }),
+    thumb: (ownerState: SwitchUnstyledOwnerState) => ({
+      className: `bg-white block w-3.5 h-3.5 rounded-full relative top-[3px] ${
+        ownerState.checked ? 'left-[3px]' : 'left-[14px]'
+      }`,
+    }),
+    input: { className: 'absolute w-full h-full inset-0 opacity-0 z-10 m-0' },
+  };
+
+  return <SwitchUnstyled {...props} slotProps={slotProps} />;
+}
+```
+
+See our [Working with Tailwind CSS guide](/base/guides/working-with-tailwind-css/) for more information about integrating MUI Base and Tailwind CSS.
+
+#### Styled components
+
+If you use a CSS-in-JS solution with a styled-components-like API (such as [MUI System](/system/getting-started/overview/) or [Emotion](https://emotion.sh/docs/introduction)), the best method is to provide the styled subcomponents using the [`slots` prop](#overriding-subcomponent-slots), as shown in the [demo below](#overriding-subcomponent-slots).
+
+Alternatively, you can wrap the whole unstyled component in a `styled` utility and target the individual subcomponents using CSS classes:
+
+{{"demo": "StylingSlotsSingleComponent.js", "defaultCodeOpen": true}}
+
+---
+
+### Applying custom CSS rules
 
 If you're happy with the default structure of a component's rendered HTML, you can apply custom styles to the component's classes.
 
@@ -22,7 +110,7 @@ Additionally, you can import a `[componentName]Classes` object that describes al
 If you don't use these classes, you can clean up the DOM by disabling them.
 See [Disabling default CSS classes](#disabling-default-css-classes) for instructions.
 
-## Overriding subcomponent slots
+### Overriding subcomponent slots
 
 If you want to make changes to a component's rendered HTML structure, you can override the default subcomponents ("slots") using the `slots` and/or `component` prop—see the guide on [Overriding component structure](/base/guides/overriding-component-structure/) for more details.
 
@@ -55,7 +143,41 @@ In this case, `MyCustomThumb` component receives the `ownerState` object with th
 
 You can use this object to style your component.
 
-## Creating custom components using hooks
+### Customizing slot props
+
+Use the `slotProps` prop to customize the inner component props.
+The most common use case is setting a class name, but you can set any prop, including event handlers.
+
+The following example shows how to add a custom class to two of the Unstyled Switch's slots:
+
+```tsx
+function Switch(props: SwitchUnstyledProps) {
+  const slotProps: SwitchUnstyledProps['slotProps'] = {
+    thumb: {
+      className: 'my-thumb',
+    },
+    track: {
+      className: 'my-track',
+    },
+  };
+
+  return <SwitchUnstyled {...props} slotProps={slotProps} />;
+}
+```
+
+The `switch:thumb` and `switch:class` are added unconditionally—they will always be present on the Switch component.
+
+You may need to apply a class only when a component is in a particular state.
+A good example is adding `on` and `off` classes to a Switch based on its checked state, as shown in the demo below:
+
+{{"demo": "SlotPropsCallback.js", "defaultCodeOpen": true}}
+
+Here, instead of an object with props, the root slot receives a callback function.
+Its only parameter is `ownerState`, which is an object that describes the state of the "owner component"—the Unstyled Switch in this case.
+The `ownerState` holds all the props of the owner component (with defaults applied where applicable) and is augmented with the internal state of the component.
+In the case of the Unstyled Select, the additional information includes the `checked`, `disabled`, `focusVisible`, and `readOnly` boolean fields.
+
+### Creating custom components using hooks
 
 If you need complete control over a component's rendered HTML structure, you can build it with hooks.
 

From 6746440b292f8bb4169b0dab379ebc6c16e9db80 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Wed, 5 Apr 2023 12:08:25 -0500
Subject: [PATCH 18/25] merge noise

---
 docs/data/base/getting-started/customization/customization.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/data/base/getting-started/customization/customization.md b/docs/data/base/getting-started/customization/customization.md
index b55598d415f38f..a2fe7b97784065 100644
--- a/docs/data/base/getting-started/customization/customization.md
+++ b/docs/data/base/getting-started/customization/customization.md
@@ -6,8 +6,6 @@ With MUI Base, you have the freedom to decide how much you want to customize a c
 
 ## Styling the components
 
-> > > > > > > master
-
 This section reviews several methods of customization that are available: applying custom CSS rules, overriding default subcomponent slots, customizing the slot props, and using hooks to build fully custom components.
 
 ### Which option to choose?

From ae424cf52b4fa5da5f95c378c3b230d0df0a5462 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Wed, 5 Apr 2023 12:12:10 -0500
Subject: [PATCH 19/25] base UI

---
 .../overriding-component-structure.md                       | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
index 3dd51866519bf6..b014266a40488f 100644
--- a/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
+++ b/docs/data/base/guides/overriding-component-structure/overriding-component-structure.md
@@ -1,8 +1,8 @@
 # Overriding component structure
 
-<p class="description">Learn how to override the default DOM structure of MUI Base components.</p>
+<p class="description">Learn how to override the default DOM structure of Base UI components.</p>
 
-MUI Base components are designed to suit the widest possible range of use cases, but you may occasionally need to change how a component's structure is rendered in the DOM.
+Base UI components are designed to suit the widest possible range of use cases, but you may occasionally need to change how a component's structure is rendered in the DOM.
 
 To understand how to do this, it helps to have an accurate mental model of MUI components.
 
@@ -13,7 +13,7 @@ Slots are most commonly filled by HTML tags, but may also be filled by React com
 
 All components contain a root slot that defines their primary node in the DOM tree; more complex components also contain additional interior slots named after the elements they represent.
 
-All _non-utility_ MUI Base components accept two props for overriding their rendered HTML structure:
+All _non-utility_ Base UI components accept two props for overriding their rendered HTML structure:
 
 - `component`—to override the root slot
 - `slots`—to override any interior slots (when present) as well as the root

From 56a189fa448ad2a687bbe739aa986476e34b13cd Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Wed, 5 Apr 2023 13:06:49 -0500
Subject: [PATCH 20/25] ci checks

---
 .../OverridingInternalSlot.tsx.preview            | 15 +++++++++++++++
 .../OverridingRootSlot.tsx.preview                |  9 ++++++++-
 docs/translations/translations.json               |  1 +
 3 files changed, 24 insertions(+), 1 deletion(-)
 create mode 100644 docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx.preview

diff --git a/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx.preview b/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx.preview
new file mode 100644
index 00000000000000..a03695efb5e7d1
--- /dev/null
+++ b/docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx.preview
@@ -0,0 +1,15 @@
+<Autocomplete
+  open
+  multiple
+  disableClearable
+  placeholder="Type to search"
+  options={[
+    { label: '🆘 Need help' },
+    { label: '✨ Improvement' },
+    { label: '🚀 New feature' },
+    { label: '🐛 Bug fix' },
+  ]}
+  slots={{
+    listbox: AutocompleteListbox,
+  }}
+/>
\ No newline at end of file
diff --git a/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx.preview b/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx.preview
index 1a3d44bd97a2fa..a5f28043022c0d 100644
--- a/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx.preview
+++ b/docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx.preview
@@ -1 +1,8 @@
-<Button component="div">Button</Button>
\ No newline at end of file
+<Button
+  component="a"
+  href="https://mui.com/about-us/"
+  target="_blank"
+  rel="noopener noreferrer"
+>
+  About us
+</Button>
\ No newline at end of file
diff --git a/docs/translations/translations.json b/docs/translations/translations.json
index d38b00609101ef..910d7be0a77558 100644
--- a/docs/translations/translations.json
+++ b/docs/translations/translations.json
@@ -439,6 +439,7 @@
     "/joy-ui/customization/default-theme-viewer": "Default theme viewer",
     "/joy-ui/customization/theme-builder": "Theme builder",
     "/joy-ui/guides": "How-to guides",
+    "/joy-ui/guides/overriding-component-structure": "Overriding component structure",
     "/joy-ui/guides/using-joy-ui-and-material-ui-together": "Joy UI and Material UI together",
     "/joy-ui/guides/using-icon-libraries": "Using icon libraries"
   }

From 2229456411eab63c1250d68343fc265ddac89e35 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Wed, 5 Apr 2023 15:34:17 -0500
Subject: [PATCH 21/25] StylingSlots.js

---
 docs/data/base/getting-started/customization/customization.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/data/base/getting-started/customization/customization.md b/docs/data/base/getting-started/customization/customization.md
index a2fe7b97784065..bb8b985888c86c 100644
--- a/docs/data/base/getting-started/customization/customization.md
+++ b/docs/data/base/getting-started/customization/customization.md
@@ -88,7 +88,7 @@ If you use a CSS-in-JS solution with a styled-components-like API (such as [MUI
 
 Alternatively, you can wrap the whole unstyled component in a `styled` utility and target the individual subcomponents using CSS classes:
 
-{{"demo": "StylingSlotsSingleComponent.js", "defaultCodeOpen": true}}
+{{"demo": "StylingSlots.js", "defaultCodeOpen": true}}
 
 ---
 

From 62cc56148151586f0b64f0367ada72d056a5fa47 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Wed, 5 Apr 2023 15:40:01 -0500
Subject: [PATCH 22/25] StylingSlotsSingleComponent

---
 .../{StylingSlots.js => StylingSlotsSingleComponent.js}         | 0
 .../{StylingSlots.tsx => StylingSlotsSingleComponent.tsx}       | 0
 ...lots.tsx.preview => StylingSlotsSingleComponent.tsx.preview} | 0
 docs/data/base/getting-started/customization/customization.md   | 2 +-
 4 files changed, 1 insertion(+), 1 deletion(-)
 rename docs/data/base/getting-started/customization/{StylingSlots.js => StylingSlotsSingleComponent.js} (100%)
 rename docs/data/base/getting-started/customization/{StylingSlots.tsx => StylingSlotsSingleComponent.tsx} (100%)
 rename docs/data/base/getting-started/customization/{StylingSlots.tsx.preview => StylingSlotsSingleComponent.tsx.preview} (100%)

diff --git a/docs/data/base/getting-started/customization/StylingSlots.js b/docs/data/base/getting-started/customization/StylingSlotsSingleComponent.js
similarity index 100%
rename from docs/data/base/getting-started/customization/StylingSlots.js
rename to docs/data/base/getting-started/customization/StylingSlotsSingleComponent.js
diff --git a/docs/data/base/getting-started/customization/StylingSlots.tsx b/docs/data/base/getting-started/customization/StylingSlotsSingleComponent.tsx
similarity index 100%
rename from docs/data/base/getting-started/customization/StylingSlots.tsx
rename to docs/data/base/getting-started/customization/StylingSlotsSingleComponent.tsx
diff --git a/docs/data/base/getting-started/customization/StylingSlots.tsx.preview b/docs/data/base/getting-started/customization/StylingSlotsSingleComponent.tsx.preview
similarity index 100%
rename from docs/data/base/getting-started/customization/StylingSlots.tsx.preview
rename to docs/data/base/getting-started/customization/StylingSlotsSingleComponent.tsx.preview
diff --git a/docs/data/base/getting-started/customization/customization.md b/docs/data/base/getting-started/customization/customization.md
index bb8b985888c86c..a2fe7b97784065 100644
--- a/docs/data/base/getting-started/customization/customization.md
+++ b/docs/data/base/getting-started/customization/customization.md
@@ -88,7 +88,7 @@ If you use a CSS-in-JS solution with a styled-components-like API (such as [MUI
 
 Alternatively, you can wrap the whole unstyled component in a `styled` utility and target the individual subcomponents using CSS classes:
 
-{{"demo": "StylingSlots.js", "defaultCodeOpen": true}}
+{{"demo": "StylingSlotsSingleComponent.js", "defaultCodeOpen": true}}
 
 ---
 

From d9ea759e5d380671c3bdce953a99fb01460ce402 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Wed, 5 Apr 2023 15:45:14 -0500
Subject: [PATCH 23/25] hopefully resolve merge issues

---
 .../customization/SlotPropsCallback.js        | 74 +++++++++++++++++++
 .../customization/SlotPropsCallback.tsx       | 74 +++++++++++++++++++
 .../SlotPropsCallback.tsx.preview             |  3 +
 .../customization/StylingSlots.js             | 63 ++++++++++++++++
 .../customization/StylingSlots.tsx            | 63 ++++++++++++++++
 .../customization/StylingSlots.tsx.preview    |  1 +
 .../StylingSlotsSingleComponent.js            | 68 ++++++++---------
 .../StylingSlotsSingleComponent.tsx           | 68 ++++++++---------
 .../StylingSlotsSingleComponent.tsx.preview   |  2 +-
 .../customization/customization.md            |  6 +-
 10 files changed, 350 insertions(+), 72 deletions(-)
 create mode 100644 docs/data/base/getting-started/customization/SlotPropsCallback.js
 create mode 100644 docs/data/base/getting-started/customization/SlotPropsCallback.tsx
 create mode 100644 docs/data/base/getting-started/customization/SlotPropsCallback.tsx.preview
 create mode 100644 docs/data/base/getting-started/customization/StylingSlots.js
 create mode 100644 docs/data/base/getting-started/customization/StylingSlots.tsx
 create mode 100644 docs/data/base/getting-started/customization/StylingSlots.tsx.preview

diff --git a/docs/data/base/getting-started/customization/SlotPropsCallback.js b/docs/data/base/getting-started/customization/SlotPropsCallback.js
new file mode 100644
index 00000000000000..38acb9aeb00691
--- /dev/null
+++ b/docs/data/base/getting-started/customization/SlotPropsCallback.js
@@ -0,0 +1,74 @@
+import * as React from 'react';
+import SwitchUnstyled from '@mui/base/SwitchUnstyled';
+
+const css = `
+  .my-switch {
+    font-size: 0;
+    position: relative;
+    display: inline-block;
+    width: 32px;
+    height: 20px;
+    background: #B3C3D3;
+    border-radius: 10px;
+    margin: 10px;
+    cursor: pointer;
+  }
+
+  .my-switch.on {
+    background: #007FFF;
+  }
+
+  .my-switch.focused .thumb {
+    background-color: rgba(255, 255, 255, 1);
+    box-shadow: 0 0 1px 8px rgba(0, 0, 0, 0.25);
+  }
+
+  .my-switch .thumb {
+    display: block;
+    width: 14px;
+    height: 14px;
+    top: 3px;
+    left: 3px;
+    border-radius: 16px;
+    background-color: #FFF;
+    position: relative;
+    transition: all 200ms ease;
+  }
+
+  .my-switch.on .thumb {
+    left: 14px;
+    top: 3px;
+    background-color: #FFF;
+  }
+
+  .my-switch .input {
+    cursor: inherit;
+    position: absolute;
+    width: 100%;
+    height: 100%;
+    top: 0;
+    left: 0;
+    opacity: 0;
+    z-index: 1;
+    margin: 0;
+  }`;
+
+export default function SlotPropsCallback() {
+  const slotProps = {
+    root: (ownerState) => ({
+      className: `my-switch ${ownerState.checked ? 'on' : 'off'} ${
+        ownerState.focusVisible ? 'focused' : ''
+      }`,
+    }),
+    thumb: { className: 'thumb' },
+    input: { className: 'input' },
+  };
+
+  return (
+    <div>
+      <style type="text/css">{css}</style>
+
+      <SwitchUnstyled slotProps={slotProps} />
+    </div>
+  );
+}
diff --git a/docs/data/base/getting-started/customization/SlotPropsCallback.tsx b/docs/data/base/getting-started/customization/SlotPropsCallback.tsx
new file mode 100644
index 00000000000000..a5ca9c603eced5
--- /dev/null
+++ b/docs/data/base/getting-started/customization/SlotPropsCallback.tsx
@@ -0,0 +1,74 @@
+import * as React from 'react';
+import SwitchUnstyled, { SwitchUnstyledOwnerState } from '@mui/base/SwitchUnstyled';
+
+const css = `
+  .my-switch {
+    font-size: 0;
+    position: relative;
+    display: inline-block;
+    width: 32px;
+    height: 20px;
+    background: #B3C3D3;
+    border-radius: 10px;
+    margin: 10px;
+    cursor: pointer;
+  }
+
+  .my-switch.on {
+    background: #007FFF;
+  }
+
+  .my-switch.focused .thumb {
+    background-color: rgba(255, 255, 255, 1);
+    box-shadow: 0 0 1px 8px rgba(0, 0, 0, 0.25);
+  }
+
+  .my-switch .thumb {
+    display: block;
+    width: 14px;
+    height: 14px;
+    top: 3px;
+    left: 3px;
+    border-radius: 16px;
+    background-color: #FFF;
+    position: relative;
+    transition: all 200ms ease;
+  }
+
+  .my-switch.on .thumb {
+    left: 14px;
+    top: 3px;
+    background-color: #FFF;
+  }
+
+  .my-switch .input {
+    cursor: inherit;
+    position: absolute;
+    width: 100%;
+    height: 100%;
+    top: 0;
+    left: 0;
+    opacity: 0;
+    z-index: 1;
+    margin: 0;
+  }`;
+
+export default function SlotPropsCallback() {
+  const slotProps = {
+    root: (ownerState: SwitchUnstyledOwnerState) => ({
+      className: `my-switch ${ownerState.checked ? 'on' : 'off'} ${
+        ownerState.focusVisible ? 'focused' : ''
+      }`,
+    }),
+    thumb: { className: 'thumb' },
+    input: { className: 'input' },
+  };
+
+  return (
+    <div>
+      <style type="text/css">{css}</style>
+
+      <SwitchUnstyled slotProps={slotProps} />
+    </div>
+  );
+}
diff --git a/docs/data/base/getting-started/customization/SlotPropsCallback.tsx.preview b/docs/data/base/getting-started/customization/SlotPropsCallback.tsx.preview
new file mode 100644
index 00000000000000..87913a39ea1fbb
--- /dev/null
+++ b/docs/data/base/getting-started/customization/SlotPropsCallback.tsx.preview
@@ -0,0 +1,3 @@
+<style type="text/css">{css}</style>
+
+<SwitchUnstyled slotProps={slotProps} />
\ No newline at end of file
diff --git a/docs/data/base/getting-started/customization/StylingSlots.js b/docs/data/base/getting-started/customization/StylingSlots.js
new file mode 100644
index 00000000000000..c7b511e51980ed
--- /dev/null
+++ b/docs/data/base/getting-started/customization/StylingSlots.js
@@ -0,0 +1,63 @@
+import * as React from 'react';
+import { styled } from '@mui/system';
+import SwitchUnstyled, { switchUnstyledClasses } from '@mui/base/SwitchUnstyled';
+
+const Root = styled('span')`
+  font-size: 0;
+  position: relative;
+  display: inline-block;
+  width: 32px;
+  height: 20px;
+  background: #b3c3d3;
+  border-radius: 10px;
+  margin: 10px;
+  cursor: pointer;
+
+  &.${switchUnstyledClasses.disabled} {
+    opacity: 0.4;
+    cursor: not-allowed;
+  }
+
+  &.${switchUnstyledClasses.checked} {
+    background: #007fff;
+  }
+`;
+
+const Thumb = styled('span')`
+  display: block;
+  width: 14px;
+  height: 14px;
+  top: 3px;
+  left: 3px;
+  border-radius: 16px;
+  background-color: #fff;
+  position: relative;
+  transition: all 200ms ease;
+
+  .${switchUnstyledClasses.focusVisible} & {
+    background-color: rgba(255, 255, 255, 1);
+    box-shadow: 0 0 1px 8px rgba(0, 0, 0, 0.25);
+  }
+
+  .${switchUnstyledClasses.checked} > & {
+    left: 14px;
+    top: 3px;
+    background-color: #fff;
+  }
+`;
+
+const Input = styled('input')`
+  cursor: inherit;
+  position: absolute;
+  width: 100%;
+  height: 100%;
+  top: 0;
+  left: 0;
+  opacity: 0;
+  z-index: 1;
+  margin: 0;
+`;
+
+export default function StylingSlots() {
+  return <SwitchUnstyled slots={{ root: Root, thumb: Thumb, input: Input }} />;
+}
diff --git a/docs/data/base/getting-started/customization/StylingSlots.tsx b/docs/data/base/getting-started/customization/StylingSlots.tsx
new file mode 100644
index 00000000000000..c7b511e51980ed
--- /dev/null
+++ b/docs/data/base/getting-started/customization/StylingSlots.tsx
@@ -0,0 +1,63 @@
+import * as React from 'react';
+import { styled } from '@mui/system';
+import SwitchUnstyled, { switchUnstyledClasses } from '@mui/base/SwitchUnstyled';
+
+const Root = styled('span')`
+  font-size: 0;
+  position: relative;
+  display: inline-block;
+  width: 32px;
+  height: 20px;
+  background: #b3c3d3;
+  border-radius: 10px;
+  margin: 10px;
+  cursor: pointer;
+
+  &.${switchUnstyledClasses.disabled} {
+    opacity: 0.4;
+    cursor: not-allowed;
+  }
+
+  &.${switchUnstyledClasses.checked} {
+    background: #007fff;
+  }
+`;
+
+const Thumb = styled('span')`
+  display: block;
+  width: 14px;
+  height: 14px;
+  top: 3px;
+  left: 3px;
+  border-radius: 16px;
+  background-color: #fff;
+  position: relative;
+  transition: all 200ms ease;
+
+  .${switchUnstyledClasses.focusVisible} & {
+    background-color: rgba(255, 255, 255, 1);
+    box-shadow: 0 0 1px 8px rgba(0, 0, 0, 0.25);
+  }
+
+  .${switchUnstyledClasses.checked} > & {
+    left: 14px;
+    top: 3px;
+    background-color: #fff;
+  }
+`;
+
+const Input = styled('input')`
+  cursor: inherit;
+  position: absolute;
+  width: 100%;
+  height: 100%;
+  top: 0;
+  left: 0;
+  opacity: 0;
+  z-index: 1;
+  margin: 0;
+`;
+
+export default function StylingSlots() {
+  return <SwitchUnstyled slots={{ root: Root, thumb: Thumb, input: Input }} />;
+}
diff --git a/docs/data/base/getting-started/customization/StylingSlots.tsx.preview b/docs/data/base/getting-started/customization/StylingSlots.tsx.preview
new file mode 100644
index 00000000000000..942f03ca800c9b
--- /dev/null
+++ b/docs/data/base/getting-started/customization/StylingSlots.tsx.preview
@@ -0,0 +1 @@
+<SwitchUnstyled slots={{ root: Root, thumb: Thumb, input: Input }} />
\ No newline at end of file
diff --git a/docs/data/base/getting-started/customization/StylingSlotsSingleComponent.js b/docs/data/base/getting-started/customization/StylingSlotsSingleComponent.js
index 7408f64884b891..3b3b1547cc17ca 100644
--- a/docs/data/base/getting-started/customization/StylingSlotsSingleComponent.js
+++ b/docs/data/base/getting-started/customization/StylingSlotsSingleComponent.js
@@ -2,7 +2,7 @@ import * as React from 'react';
 import { styled } from '@mui/system';
 import SwitchUnstyled, { switchUnstyledClasses } from '@mui/base/SwitchUnstyled';
 
-const Root = styled('span')`
+const Switch = styled(SwitchUnstyled)`
   font-size: 0;
   position: relative;
   display: inline-block;
@@ -13,6 +13,30 @@ const Root = styled('span')`
   margin: 10px;
   cursor: pointer;
 
+  & .${switchUnstyledClasses.thumb} {
+    display: block;
+    width: 14px;
+    height: 14px;
+    top: 3px;
+    left: 3px;
+    border-radius: 16px;
+    background-color: #fff;
+    position: relative;
+    transition: all 200ms ease;
+  }
+
+  & .${switchUnstyledClasses.input} {
+    cursor: inherit;
+    position: absolute;
+    width: 100%;
+    height: 100%;
+    top: 0;
+    left: 0;
+    opacity: 0;
+    z-index: 1;
+    margin: 0;
+  }
+
   &.${switchUnstyledClasses.disabled} {
     opacity: 0.4;
     cursor: not-allowed;
@@ -20,44 +44,20 @@ const Root = styled('span')`
 
   &.${switchUnstyledClasses.checked} {
     background: #007fff;
-  }
-`;
 
-const Thumb = styled('span')`
-  display: block;
-  width: 14px;
-  height: 14px;
-  top: 3px;
-  left: 3px;
-  border-radius: 16px;
-  background-color: #fff;
-  position: relative;
-  transition: all 200ms ease;
+    & .${switchUnstyledClasses.thumb} {
+      left: 14px;
+      top: 3px;
+      background-color: #fff;
+    }
+  }
 
-  &.${switchUnstyledClasses.focusVisible} {
+  &.${switchUnstyledClasses.focusVisible} .${switchUnstyledClasses.thumb} {
     background-color: rgba(255, 255, 255, 1);
     box-shadow: 0 0 1px 8px rgba(0, 0, 0, 0.25);
   }
-
-  &.${switchUnstyledClasses.checked} {
-    left: 14px;
-    top: 3px;
-    background-color: #fff;
-  }
-`;
-
-const Input = styled('input')`
-  cursor: inherit;
-  position: absolute;
-  width: 100%;
-  height: 100%;
-  top: 0;
-  left: 0;
-  opacity: 0;
-  z-index: 1;
-  margin: 0;
 `;
 
-export default function StylingSlots() {
-  return <SwitchUnstyled slots={{ root: Root, thumb: Thumb, input: Input }} />;
+export default function StylingSlotsSingleComponent() {
+  return <Switch />;
 }
diff --git a/docs/data/base/getting-started/customization/StylingSlotsSingleComponent.tsx b/docs/data/base/getting-started/customization/StylingSlotsSingleComponent.tsx
index 7408f64884b891..3b3b1547cc17ca 100644
--- a/docs/data/base/getting-started/customization/StylingSlotsSingleComponent.tsx
+++ b/docs/data/base/getting-started/customization/StylingSlotsSingleComponent.tsx
@@ -2,7 +2,7 @@ import * as React from 'react';
 import { styled } from '@mui/system';
 import SwitchUnstyled, { switchUnstyledClasses } from '@mui/base/SwitchUnstyled';
 
-const Root = styled('span')`
+const Switch = styled(SwitchUnstyled)`
   font-size: 0;
   position: relative;
   display: inline-block;
@@ -13,6 +13,30 @@ const Root = styled('span')`
   margin: 10px;
   cursor: pointer;
 
+  & .${switchUnstyledClasses.thumb} {
+    display: block;
+    width: 14px;
+    height: 14px;
+    top: 3px;
+    left: 3px;
+    border-radius: 16px;
+    background-color: #fff;
+    position: relative;
+    transition: all 200ms ease;
+  }
+
+  & .${switchUnstyledClasses.input} {
+    cursor: inherit;
+    position: absolute;
+    width: 100%;
+    height: 100%;
+    top: 0;
+    left: 0;
+    opacity: 0;
+    z-index: 1;
+    margin: 0;
+  }
+
   &.${switchUnstyledClasses.disabled} {
     opacity: 0.4;
     cursor: not-allowed;
@@ -20,44 +44,20 @@ const Root = styled('span')`
 
   &.${switchUnstyledClasses.checked} {
     background: #007fff;
-  }
-`;
 
-const Thumb = styled('span')`
-  display: block;
-  width: 14px;
-  height: 14px;
-  top: 3px;
-  left: 3px;
-  border-radius: 16px;
-  background-color: #fff;
-  position: relative;
-  transition: all 200ms ease;
+    & .${switchUnstyledClasses.thumb} {
+      left: 14px;
+      top: 3px;
+      background-color: #fff;
+    }
+  }
 
-  &.${switchUnstyledClasses.focusVisible} {
+  &.${switchUnstyledClasses.focusVisible} .${switchUnstyledClasses.thumb} {
     background-color: rgba(255, 255, 255, 1);
     box-shadow: 0 0 1px 8px rgba(0, 0, 0, 0.25);
   }
-
-  &.${switchUnstyledClasses.checked} {
-    left: 14px;
-    top: 3px;
-    background-color: #fff;
-  }
-`;
-
-const Input = styled('input')`
-  cursor: inherit;
-  position: absolute;
-  width: 100%;
-  height: 100%;
-  top: 0;
-  left: 0;
-  opacity: 0;
-  z-index: 1;
-  margin: 0;
 `;
 
-export default function StylingSlots() {
-  return <SwitchUnstyled slots={{ root: Root, thumb: Thumb, input: Input }} />;
+export default function StylingSlotsSingleComponent() {
+  return <Switch />;
 }
diff --git a/docs/data/base/getting-started/customization/StylingSlotsSingleComponent.tsx.preview b/docs/data/base/getting-started/customization/StylingSlotsSingleComponent.tsx.preview
index 942f03ca800c9b..0ff96d201086e7 100644
--- a/docs/data/base/getting-started/customization/StylingSlotsSingleComponent.tsx.preview
+++ b/docs/data/base/getting-started/customization/StylingSlotsSingleComponent.tsx.preview
@@ -1 +1 @@
-<SwitchUnstyled slots={{ root: Root, thumb: Thumb, input: Input }} />
\ No newline at end of file
+<Switch />
\ No newline at end of file
diff --git a/docs/data/base/getting-started/customization/customization.md b/docs/data/base/getting-started/customization/customization.md
index a2fe7b97784065..eba21e44e7d92f 100644
--- a/docs/data/base/getting-started/customization/customization.md
+++ b/docs/data/base/getting-started/customization/customization.md
@@ -110,9 +110,9 @@ See [Disabling default CSS classes](#disabling-default-css-classes) for instruct
 
 ### Overriding subcomponent slots
 
-If you want to make changes to a component's rendered HTML structure, you can override the default subcomponents ("slots") using the `slots` and/or `component` prop—see the guide on [Overriding component structure](/base/guides/overriding-component-structure/) for more details.
+If you want to make changes to a component's rendered HTML structure, you can override the default subcomponents ("slots") using the `slots` and/or `component` prop—see ["Shared props" on the Base Usage page](/base/getting-started/usage/#shared-props) for more details.
 
-The following demo uses the [Unstyled Switch](/base/react-switch/) to show how to create a styled component by applying styles to three of its subcomponent slots: `root`, `thumb`, and `input`.
+The following demo uses [SwitchUnstyled](/base/react-switch/) to show how to create a styled component by applying styles to three of its subcomponent slots: `root`, `thumb`, and `input`.
 
 Note that although this demo uses [MUI System](/system/styled/) as a styling solution, you are free to choose any alternative.
 
@@ -184,7 +184,7 @@ See ["Components vs. hooks" on the Base Usage page](/base/getting-started/usage/
 
 Hooks return the current state of the component (e.g. `checked`, `disabled`, `open`, etc.) and provide functions that return props you can apply to your fully custom components.
 
-In the case of the [Unstyled Switch](/base/react-switch/), the component is accompanied by the `useSwitch` hook which gives you all of the functionality without any structure.
+In the case of [SwitchUnstyled](/base/react-switch/), the component is accompanied by the `useSwitch` hook which gives you all of the functionality without any structure.
 
 It returns the following object:
 

From b5a0a2bb71f5c005b1a0d1dd9d7000e7144075f6 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Wed, 5 Apr 2023 16:50:44 -0500
Subject: [PATCH 24/25] usage page regression

---
 docs/data/base/getting-started/usage/usage.md | 78 +++++++++++++++++++
 1 file changed, 78 insertions(+)

diff --git a/docs/data/base/getting-started/usage/usage.md b/docs/data/base/getting-started/usage/usage.md
index 2357be7b32af40..fdf07d6dfa734f 100644
--- a/docs/data/base/getting-started/usage/usage.md
+++ b/docs/data/base/getting-started/usage/usage.md
@@ -34,6 +34,84 @@ To ensure proper rendering and touch zooming for all devices, add the responsive
 <meta name="viewport" content="initial-scale=1, width=device-width" />
 ```
 
+## Shared props
+
+Base components are self-supporting and fully functional in isolation.
+
+Each component has its own unique API, but all _non-utility_ components accept the following shared props:
+
+### slots
+
+The `slots` prop is an object that lets you override any interior subcomponents—known as **slots**—of the base component itself.
+
+:::info
+Each component contains a root slot, and other appropriate slots based on the nature of the component.
+For example, the Unstyled Badge contains two slots:
+
+- `root`: the container element that wraps the children.
+- `badge`: the badge element itself.
+  :::
+
+You can use the `slots` prop to override default slots with either custom components or HTML elements.
+
+For example, the Unstyled Badge component renders a `<span>` by default.
+The code snippet below shows how to override this by assigning a `<div>` to the root slot:
+
+```jsx
+<BadgeUnstyled slots={{ root: 'div' }} />
+```
+
+### component
+
+The `component` prop provides a shortcut to `slots.root`.
+This is useful if you are only overriding the root element of the component.
+
+The code snippet below shows how to override the root element of the Unstyled Badge component using the `component` prop:
+
+```jsx
+<BadgeUnstyled component="div" />
+```
+
+:::warning
+If the root slot is customized with both the `component` and `slots` props, then `component` will take precedence.
+:::
+
+### slotProps
+
+The `slotProps` prop is an object that contains the props for all slots within a component.
+You can use it to define additional custom props for a component's interior elements.
+
+For example, the code snippet below shows how to add a custom CSS class to the badge slot of the Unstyled Badge component:
+
+```jsx
+<BadgeUnstyled slotProps={{ badge: { className: 'my-badge' } }} />
+```
+
+All additional props placed on the primary component are also propagated into the root slot (just as if they were placed in `slotProps.root`).
+
+These two examples are equivalent:
+
+```jsx
+<BadgeUnstyled id="badge1">
+```
+
+```jsx
+<BadgeUnstyled slotProps={{ root: { id: 'badge1' } }}>
+```
+
+:::warning
+If both `slotProps.root` and additional props have the same keys but different values, the `slotProps.root` props will take precedence.
+This does not apply to classes or the `style` prop—they will be merged instead.
+:::
+
+### Best practices
+
+If you are customizing a component like the [Unstyled Button](/base/react-button/) that only has a root slot, you may prefer to use the more succinct `component` prop instead of `slots`.
+
+Overriding with `component` lets you apply the attributes of that element directly to the root.
+For instance, if you replace the Unstyled Button root with an `<li>` tag, you can add the `<li>` attribute `value` directly to the component.
+If you did the same with `slots.root`, you would need to place this attribute on the `slotProps.root` object in order to avoid a TypeScript error.
+
 ## Components vs. hooks
 
 MUI Base includes two kinds of building blocks: **components** and **hooks**.

From 1e9ca3fdb128243c6bbe088b94d714e2d6dafde1 Mon Sep 17 00:00:00 2001
From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
Date: Fri, 7 Apr 2023 09:52:48 -0500
Subject: [PATCH 25/25] Update
 docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md

Co-authored-by: Siriwat K <siriwatkunaporn@gmail.com>
Signed-off-by: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com>
---
 .../overriding-component-structure.md                           | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md b/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
index 2d5392ea0ed053..072bf91c3c58d0 100644
--- a/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
+++ b/docs/data/joy/guides/overriding-component-structure/overriding-component-structure.md
@@ -86,7 +86,7 @@ Use `component` or `slotProps.{slot}.component` prop to override the element by
 Use `slots` prop to replace the slot's styles and functionality with your custom component.
 
 Overriding with `component` lets you apply the attributes of that element directly to the root.
-For instance, if you replace the Unstyled Button root with an `<li>` tag, you can add the `<li>` attribute `value` directly to the component.
+For instance, if you override the Button's root with an `<li>` tag, you can add the `<li>` attribute `value` directly to the component.
 If you did the same with `slots.root`, you would need to place this attribute on the `slotProps.root` object in order to avoid a TypeScript error.
 
 Be mindful of your rendered DOM structure when overriding the slots of more complex components.