-
-
Notifications
You must be signed in to change notification settings - Fork 31.9k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[docs] Add guides to overriding component structure in Base UI and Jo…
…y UI docs (#34990) Signed-off-by: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Co-authored-by: Siriwat K <siriwatkunaporn@gmail.com>
- Loading branch information
1 parent
01f329a
commit 9e8670e
Showing
19 changed files
with
371 additions
and
0 deletions.
There are no files selected for viewing
12 changes: 12 additions & 0 deletions
12
docs/data/base/guides/overriding-component-structure/OverridingInternalSlot.js
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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> | ||
); | ||
} |
12 changes: 12 additions & 0 deletions
12
docs/data/base/guides/overriding-component-structure/OverridingInternalSlot.tsx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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> | ||
); | ||
} |
4 changes: 4 additions & 0 deletions
4
docs/data/base/guides/overriding-component-structure/OverridingInternalSlot.tsx.preview
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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> |
6 changes: 6 additions & 0 deletions
6
docs/data/base/guides/overriding-component-structure/OverridingRootSlot.js
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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>; | ||
} |
6 changes: 6 additions & 0 deletions
6
docs/data/base/guides/overriding-component-structure/OverridingRootSlot.tsx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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>; | ||
} |
1 change: 1 addition & 0 deletions
1
docs/data/base/guides/overriding-component-structure/OverridingRootSlot.tsx.preview
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
<ButtonUnstyled component="div">Button</ButtonUnstyled> |
107 changes: 107 additions & 0 deletions
107
...ta/base/guides/overriding-component-structure/overriding-component-structure.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,107 @@ | ||
# Overriding component structure | ||
|
||
<p class="description">Learn how to override the default DOM structure of Base UI components.</p> | ||
|
||
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. | ||
|
||
## 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_ 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 | ||
|
||
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. | ||
|
||
For example, the [Unstyled Button's](/base/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 demo below shows how to replace the Button's `<button>` tag with a `<div>`: | ||
|
||
{{"demo": "OverridingRootSlot.js"}} | ||
|
||
:::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 | ||
|
||
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 [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. | ||
|
||
### The slots prop | ||
|
||
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"}} | ||
|
||
Note that you can also use the `slots` prop to override the root slot: | ||
|
||
```jsx | ||
// This: | ||
<SelectUnstyled slots={{ root: 'span' }} /> | ||
|
||
// ...is the same as this: | ||
<SelectUnstyled component="span"> | ||
``` | ||
|
||
But if you try to override the root slot with both `component` and `slots`, then `component` will take precedence: | ||
|
||
```jsx | ||
// This: | ||
<SelectUnstyled 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 [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 | ||
<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 | ||
|
||
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
26 changes: 26 additions & 0 deletions
26
docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.js
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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> | ||
); | ||
} |
26 changes: 26 additions & 0 deletions
26
docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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> | ||
); | ||
} |
15 changes: 15 additions & 0 deletions
15
docs/data/joy/guides/overriding-component-structure/OverridingInternalSlot.tsx.preview
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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, | ||
}} | ||
/> |
15 changes: 15 additions & 0 deletions
15
docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.js
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,15 @@ | ||
import * as React from 'react'; | ||
import Button from '@mui/joy/Button'; | ||
|
||
export default function DivButton() { | ||
return ( | ||
<Button | ||
component="a" | ||
href="https://mui.com/about-us/" | ||
target="_blank" | ||
rel="noopener noreferrer" | ||
> | ||
About us | ||
</Button> | ||
); | ||
} |
15 changes: 15 additions & 0 deletions
15
docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,15 @@ | ||
import * as React from 'react'; | ||
import Button from '@mui/joy/Button'; | ||
|
||
export default function DivButton() { | ||
return ( | ||
<Button | ||
component="a" | ||
href="https://mui.com/about-us/" | ||
target="_blank" | ||
rel="noopener noreferrer" | ||
> | ||
About us | ||
</Button> | ||
); | ||
} |
8 changes: 8 additions & 0 deletions
8
docs/data/joy/guides/overriding-component-structure/OverridingRootSlot.tsx.preview
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
<Button | ||
component="a" | ||
href="https://mui.com/about-us/" | ||
target="_blank" | ||
rel="noopener noreferrer" | ||
> | ||
About us | ||
</Button> |
94 changes: 94 additions & 0 deletions
94
...ata/joy/guides/overriding-component-structure/overriding-component-structure.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,94 @@ | ||
# 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 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. | ||
|
||
## 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 | ||
- `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. 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). | ||
|
||
### 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 `<a>` to create a link button: | ||
|
||
{{"demo": "OverridingRootSlot.js"}} | ||
|
||
:::info | ||
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 | ||
|
||
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 [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 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"}} | ||
|
||
### 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 `data-testid` to the listbox slot of the [Autocomplete](/joy-ui/react-autocomplete/) component: | ||
|
||
```jsx | ||
<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 | ||
<Autocomplete id="badge1"> | ||
``` | ||
|
||
```jsx | ||
<Autocomplete 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 | ||
|
||
Use `component` or `slotProps.{slot}.component` prop to override the element by preserving the styles of the 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 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. | ||
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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} />; | ||
} |
Oops, something went wrong.