Usage

Learn the basics of working with MUI Base components.

Getting started

The following code snippet demonstrates a simple app that uses the MUI Base ButtonUnstyled component:

import * as React from 'react';
import ButtonUnstyled from '@mui/base/ButtonUnstyled';

function App() {
  return (
    <div>
      <ButtonUnstyled>Hello World</ButtonUnstyled>
    </div>
  );
}

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>:

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:

components

The components prop is an object that lets you override any interior subcomponents ("slots") of the base component itself.

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

For example, the BadgeUnstyled component renders a <span> by default. The code snippet below shows how to override this by assigning a <div> to the Root element:

<BadgeUnstyled components={{ Root: 'div' }} />

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.

The code snippet below shows how to override the Root element of the BadgeUnstyled component using the component prop:

<BadgeUnstyled component="div" />

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:

<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).

These two examples are equivalent:

<BadgeUnstyled id="badge1">

<BadgeUnstyled componentsProps={{ root: { id: 'badge1' } }}>

Components vs. hooks

MUI Base includes two kinds of building blocks: components and hooks.

Many Base components are implemented with the help of hooks. (Visit the React documentation on hooks to get up to speed on this concept.)

You can use components or hooks—or a combination thereof—when building custom components. Each option has its own trade-offs:

Components

Pros

• Usually require less code to implement
• Equipped with accessibility features by default

Cons

• Less control over the structure of the rendered HTML

Hooks

Pros

• Complete control over rendered HTML structure

Cons

• Usually require more code to implement
• Extra steps necessary to make the resulting component accessible

Details on usage of hooks can be found in their corresponding component docs.