Skip to content

Commit

Permalink
[docs] Improve the Base Usage page (#33272)
Browse files Browse the repository at this point in the history
  • Loading branch information
samuelsycamore committed Aug 15, 2022
1 parent 6f1819e commit 67ea8eb
Showing 1 changed file with 34 additions and 14 deletions.
48 changes: 34 additions & 14 deletions docs/data/base/getting-started/usage/usage.md
Expand Up @@ -10,7 +10,7 @@ The following code snippet demonstrates a simple app that uses the MUI Base [`Bu
import * as React from 'react';
import ButtonUnstyled from '@mui/base/ButtonUnstyled';

function App() {
export default function MyApp() {
return (
<div>
<ButtonUnstyled>Hello World</ButtonUnstyled>
Expand All @@ -20,28 +20,32 @@ function App() {
```

You can play around with this code in the interactive Code Sandbox demo below.
Try importing an `InputUnstyled` component and adding it to the `<div>`:
Try importing an [`InputUnstyled`](/base/react-input/) component and adding it to the `<div>`:

{{"demo": "Usage.js", "hideToolbar": true, "bg": true}}

## Shared props

Base components are self-supporting and fully functional in isolation.

Each component has its own unique API, but all components accept the following shared props:
Each component has its own unique API, but all _non-utility_ components accept the following shared props:

### components

The `components` prop is an object that lets you override any interior subcomponents ("slots") of the base component itself.
The `components` 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 many complex components (such as [`BadgeUnstyled`](/base/react-badge/)) are composed of additional subcomponents that can be customized.
:::
Each component contains a root slot, and other appropriate slots based on the nature of the component.
For example, the `BadgeUnstyled` contains two slots:

- `root`: the container element that wraps the children.
- `badge`: the badge element itself.
:::

You can use the `components` prop to replace subcomponents with either custom components or HTML elements.
You can use the `components` prop to override default slots with either custom components or HTML elements.

For example, the [`BadgeUnstyled`](/base/react-badge/) component renders a `<span>` by default.
The code snippet below shows how to override this by assigning a `<div>` to the `Root` element:
The code snippet below shows how to override this by assigning a `<div>` to the root slot:

```jsx
<BadgeUnstyled components={{ Root: 'div' }} />
Expand All @@ -50,30 +54,34 @@ The code snippet below shows how to override this by assigning a `<div>` to the
### component

The (singular) `component` prop provides a shortcut to `components.Root`.
This is useful if you are only overriding the `Root` element of the component.
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 [`BadgeUnstyled`](/base/react-badge/) component using the `component` prop:
The code snippet below shows how to override the root element of the [`BadgeUnstyled`](/base/react-badge/) component using the `component` prop:

```jsx
<BadgeUnstyled component="div" />
```

:::warning
**Note**: if both `components.Root` and `component` are specified, `component` takes precedence.
If the root slot is customized with both the `component` and `components` props, then `component` will take precedence.
:::

### componentsProps

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 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 `BadgeUnstyled` component:
For example, the code snippet below shows how to add a custom CSS class to the badge slot of the `BadgeUnstyled` component:

```jsx
<BadgeUnstyled componentsProps={{ 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 `componentsProps.root`).
:::warning
Note that `componentsProps` slot names are written in lowercase (`root`) while `components` slot names are capitalized (`Root`).
:::

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:

Expand All @@ -86,9 +94,18 @@ These two examples are equivalent:
```

:::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 and the `style` prop (they will be merged instead).
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 component like [`ButtonUnstyled`](/base/react-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 `ButtonUnstyled` 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.

## Components vs. hooks

MUI Base includes two kinds of building blocks: **components** and **hooks**.
Expand All @@ -101,6 +118,9 @@ Many Base components are implemented with the help of hooks.
(Visit the [React documentation on hooks](https://reactjs.org/docs/hooks-intro.html) to get up to speed on this concept.)

You can use components or hooks—or a combination thereof—when building custom components.

In general, we recommend that you begin building with the component, and if you find that you are too limited by the customization options available, then consider refactoring your component to use the corresponding hook instead.

Each option has its own trade-offs:

### Components
Expand Down

0 comments on commit 67ea8eb

Please sign in to comment.