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';

export default function MyApp() {
  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 non-utility components accept the following shared props:

components

The components prop is an object that lets you override any interior subcomponents—known as slots—of the base component itself.

You can use the components prop to override default slots 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 slot:

<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' } }}>

Best practices

If you are customizing a component like ButtonUnstyled 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.

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.

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

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.