Customizing Base UI components

There are several ways to customize Base UI components, from applying custom CSS rules to building fully custom components using hooks.

With Base UI, you have the freedom to decide how much you want to customize a component's structure and style.

Styling the components

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 Base UI. 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 Base UI. 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 or specify your own classes and reference them in your stylesheets.

CSS Modules

When working with CSS Modules, the simplest approach is to specify custom classes using slotProps, as shown below:

import clsx from 'clsx';
import classes from './styles.module.css';

export default function Switch(props) {
  const slotProps = {
    root: (ownerState: SwitchOwnerState) => ({
      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 <Switch {...props} slotProps={slotProps} />;
}

In this example we're using the clsx utility to reduce the effort needed to apply class names conditionally.

Tailwind CSS

Use slotProps to apply custom styles using Tailwind CSS, as shown below:

export default function Switch(props) {
  const slotProps = {
    root: (ownerState: SwitchOwnerState) => ({
      className: `inline-block w-8 h-5 rounded-full cursor-pointer relative ${
        ownerState.checked ? 'bg-cyan-500' : 'bg-zinc-400'
      }`,
    }),
    thumb: (ownerState: SwitchOwnerState) => ({
      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 <Switch {...props} slotProps={slotProps} />;
}

See our Working with Tailwind CSS guide for more information about integrating Base UI and Tailwind CSS.

Styled components

If you use a CSS-in-JS solution with a styled-components-like API (such as MUI System or Emotion), the best method is to provide the styled subcomponents using the slots prop, as shown in the demo below.

Alternatively, you can wrap the whole unstyled component in a styled utility and target the individual subcomponents using CSS classes:

import * as React from 'react';
import { styled } from '@mui/system';
import Switch, { switchClasses } from '@mui/base/Switch';

const StyledSwitch = styled(Switch)`
  font-size: 0;
  position: relative;
  display: inline-block;
  width: 32px;
  height: 20px;
  background: #b3c3d3;
  border-radius: 10px;
  margin: 10px;
  cursor: pointer;

  & .${switchClasses.thumb} {
    display: block;
    width: 14px;
    height: 14px;
    top: 3px;
    left: 3px;
    border-radius: 16px;
    background-color: #fff;
    position: relative;
    transition: all 200ms ease;
  }

  & .${switchClasses.input} {
    cursor: inherit;
    position: absolute;
    width: 100%;
    height: 100%;
    top: 0;
    left: 0;
    opacity: 0;
    z-index: 1;
    margin: 0;
  }

  &.${switchClasses.disabled} {
    opacity: 0.4;
    cursor: not-allowed;
  }

  &.${switchClasses.checked} {
    background: #007fff;

    & .${switchClasses.thumb} {
      left: 14px;
      top: 3px;
      background-color: #fff;
    }
  }

  &.${switchClasses.focusVisible} .${switchClasses.thumb} {
    background-color: rgb(255 255 255 / 1);
    box-shadow: 0 0 1px 8px rgb(0 0 0 / 0.25);
  }
`;

export default function StylingSlotsSingleComponent() {
  return <StyledSwitch />;
}

import * as React from 'react';
import { styled } from '@mui/system';
import Switch, { switchClasses } from '@mui/base/Switch';

const StyledSwitch = styled(Switch)`
  font-size: 0;
  position: relative;
  display: inline-block;
  width: 32px;
  height: 20px;
  background: #b3c3d3;
  border-radius: 10px;
  margin: 10px;
  cursor: pointer;

  & .${switchClasses.thumb} {
    display: block;
    width: 14px;
    height: 14px;
    top: 3px;
    left: 3px;
    border-radius: 16px;
    background-color: #fff;
    position: relative;
    transition: all 200ms ease;
  }

  & .${switchClasses.input} {
    cursor: inherit;
    position: absolute;
    width: 100%;
    height: 100%;
    top: 0;
    left: 0;
    opacity: 0;
    z-index: 1;
    margin: 0;
  }

  &.${switchClasses.disabled} {
    opacity: 0.4;
    cursor: not-allowed;
  }

  &.${switchClasses.checked} {
    background: #007fff;

    & .${switchClasses.thumb} {
      left: 14px;
      top: 3px;
      background-color: #fff;
    }
  }

  &.${switchClasses.focusVisible} .${switchClasses.thumb} {
    background-color: rgb(255 255 255 / 1);
    box-shadow: 0 0 1px 8px rgb(0 0 0 / 0.25);
  }
`;

export default function StylingSlotsSingleComponent() {
  return <StyledSwitch />;
}

Press Enter to start editing

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.

Each component has its own set of classes. Some classes are static, which is to say that they are always present on the component. Others are applied conditionally—like Mui-disabled, for example, which is only present when a component is disabled.

Each component's API documentation lists all classes that the component uses. Additionally, you can import a [componentName]Classes object that describes all the classes a given component uses, as the following demo illustrates:

import * as React from 'react';
import Switch, { switchClasses } from '@mui/base/Switch';

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.${switchClasses.checked} {
    background: #007FFF;
  }

  .my-switch .${switchClasses.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.${switchClasses.checked} .${switchClasses.thumb} {
    left: 14px;
    top: 3px;
    background-color: #FFF;
  }

  .my-switch .${switchClasses.input} {
    cursor: inherit;
    position: absolute;
    width: 100%;
    height: 100%;
    top: 0;
    left: 0;
    opacity: 0;
    z-index: 1;
    margin: 0;
  }`;

export default function StylingCustomCss() {
  return (
    <div>
      <style type="text/css">{css}</style>
      <Switch className="my-switch" />
    </div>
  );
}

import * as React from 'react';
import Switch, { switchClasses } from '@mui/base/Switch';

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.${switchClasses.checked} {
    background: #007FFF;
  }

  .my-switch .${switchClasses.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.${switchClasses.checked} .${switchClasses.thumb} {
    left: 14px;
    top: 3px;
    background-color: #FFF;
  }

  .my-switch .${switchClasses.input} {
    cursor: inherit;
    position: absolute;
    width: 100%;
    height: 100%;
    top: 0;
    left: 0;
    opacity: 0;
    z-index: 1;
    margin: 0;
  }`;

export default function StylingCustomCss() {
  return (
    <div>
      <style type="text/css">{css}</style>
      <Switch className="my-switch" />
    </div>
  );
}

Press Enter to start editing

If you don't use these classes, you can clean up the DOM by disabling them. See Disabling default CSS classes for instructions.

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 "Shared props" on the Base Usage page for more details.

The following demo uses 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 as a styling solution, you are free to choose any alternative.

<Switch slots={{ root: Root, thumb: Thumb, input: Input }} />

<Switch slots={{ root: Root, thumb: Thumb, input: Input }} />

Press Enter to start editing

The components you pass in the slots prop receive the ownerState prop from the top-level component (the "owner"). By convention, it contains all props passed to the owner, merged with its rendering state.

For example:

<Switch slots={{ thumb: MyCustomThumb }} data-foo="42" />

In this case, MyCustomThumb component receives the ownerState object with the following data:

{
  checked: boolean;
  disabled: boolean;
  focusVisible: boolean;
  readOnly: boolean;
  'data-foo': string;
}

You can use this object to style your component.

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 Switch's slots:

function Switch(props: SwitchProps) {
  const slotProps: SwitchProps['slotProps'] = {
    thumb: {
      className: 'my-thumb',
    },
    track: {
      className: 'my-track',
    },
  };

  return <Switch {...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:

import * as React from 'react';
import Switch, { SwitchOwnerState } from '@mui/base/Switch';

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: SwitchOwnerState) => ({
      className: `my-switch ${ownerState.checked ? 'on' : 'off'} ${
        ownerState.focusVisible ? 'focused' : ''
      }`,
    }),
    thumb: { className: 'thumb' },
    input: { className: 'input' },
  };

  return (
    <div>
      <style type="text/css">{css}</style>

      <Switch slotProps={slotProps} />
    </div>
  );
}

import * as React from 'react';
import Switch, { SwitchOwnerState } from '@mui/base/Switch';

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: SwitchOwnerState) => ({
      className: `my-switch ${ownerState.checked ? 'on' : 'off'} ${
        ownerState.focusVisible ? 'focused' : ''
      }`,
    }),
    thumb: { className: 'thumb' },
    input: { className: 'input' },
  };

  return (
    <div>
      <style type="text/css">{css}</style>

      <Switch slotProps={slotProps} />
    </div>
  );
}

Press Enter to start editing

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

Hooks give you access to the logic that a component uses, but without any default structure. See "Components vs. hooks" on the Base Usage page for more details.

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 Switch, the component is accompanied by the useSwitch hook which gives you all of the functionality without any structure.

It returns the following object:

{
  checked: Readonly<boolean>;
  disabled: Readonly<boolean>;
  readOnly: Readonly<boolean>;
  focusVisible: Readonly<boolean>;
  getInputProps: (otherProps?: object) => SwitchInputProps;
}

The checked, disabled, readOnly, and focusVisible fields represent the state of the switch. Use them to apply styling to your HTML elements.

The getInputProps function can be used to get the props to place on an HTML <input> to make the switch accessible.

import * as React from 'react';
import clsx from 'clsx';
import useSwitch, { UseSwitchParameters } from '@mui/base/useSwitch';
import { styled } from '@mui/system';

const BasicSwitchRoot = styled('span')`
  font-size: 0;
  position: relative;
  display: inline-block;
  width: 32px;
  height: 20px;
  background: #b3c3d3;
  border-radius: 10px;
  margin: 10px;
  cursor: pointer;

  &.Switch-disabled {
    opacity: 0.4;
    cursor: not-allowed;
  }

  &.Switch-checked {
    background: #007fff;
  }
`;

const BasicSwitchInput = styled('input')`
  cursor: inherit;
  position: absolute;
  width: 100%;
  height: 100%;
  top: 0;
  left: 0;
  opacity: 0;
  z-index: 1;
  margin: 0;
`;

const BasicSwitchThumb = styled('span')`
  display: block;
  width: 14px;
  height: 14px;
  top: 3px;
  left: 3px;
  border-radius: 16px;
  background-color: #fff;
  position: relative;
  transition: all 200ms ease;

  &.Switch-focusVisible {
    background-color: rgb(255 255 255 / 1);
    box-shadow: 0 0 1px 8px rgb(0 0 0 / 0.25);
  }

  &.Switch-checked {
    left: 14px;
    top: 3px;
    background-color: #fff;
  }
`;

function BasicSwitch(props: UseSwitchParameters) {
  const { getInputProps, checked, disabled, focusVisible } = useSwitch(props);

  const stateClasses = {
    'Switch-checked': checked,
    'Switch-disabled': disabled,
    'Switch-focusVisible': focusVisible,
  };

  return (
    <BasicSwitchRoot className={clsx(stateClasses)}>
      <BasicSwitchThumb className={clsx(stateClasses)} />
      <BasicSwitchInput {...getInputProps()} aria-label="Demo switch" />
    </BasicSwitchRoot>
  );
}

export default function StylingHooks() {
  return <BasicSwitch />;
}

import * as React from 'react';
import clsx from 'clsx';
import useSwitch, { UseSwitchParameters } from '@mui/base/useSwitch';
import { styled } from '@mui/system';

const BasicSwitchRoot = styled('span')`
  font-size: 0;
  position: relative;
  display: inline-block;
  width: 32px;
  height: 20px;
  background: #b3c3d3;
  border-radius: 10px;
  margin: 10px;
  cursor: pointer;

  &.Switch-disabled {
    opacity: 0.4;
    cursor: not-allowed;
  }

  &.Switch-checked {
    background: #007fff;
  }
`;

const BasicSwitchInput = styled('input')`
  cursor: inherit;
  position: absolute;
  width: 100%;
  height: 100%;
  top: 0;
  left: 0;
  opacity: 0;
  z-index: 1;
  margin: 0;
`;

const BasicSwitchThumb = styled('span')`
  display: block;
  width: 14px;
  height: 14px;
  top: 3px;
  left: 3px;
  border-radius: 16px;
  background-color: #fff;
  position: relative;
  transition: all 200ms ease;

  &.Switch-focusVisible {
    background-color: rgb(255 255 255 / 1);
    box-shadow: 0 0 1px 8px rgb(0 0 0 / 0.25);
  }

  &.Switch-checked {
    left: 14px;
    top: 3px;
    background-color: #fff;
  }
`;

function BasicSwitch(props: UseSwitchParameters) {
  const { getInputProps, checked, disabled, focusVisible } = useSwitch(props);

  const stateClasses = {
    'Switch-checked': checked,
    'Switch-disabled': disabled,
    'Switch-focusVisible': focusVisible,
  };

  return (
    <BasicSwitchRoot className={clsx(stateClasses)}>
      <BasicSwitchThumb className={clsx(stateClasses)} />
      <BasicSwitchInput {...getInputProps()} aria-label="Demo switch" />
    </BasicSwitchRoot>
  );
}

export default function StylingHooks() {
  return <BasicSwitch />;
}

Press Enter to start editing

Disabling default CSS classes

If you don't need the built-in classes on components, you may disable them. This will clean up the DOM and can be useful especially if you apply your own classes or style components using a CSS-in-JS solution. To do this, wrap your components in a ClassNameConfigurator component (imported from @mui/base/utils):

<ClassNameConfigurator disableDefaultClasses>
  <Button>I'm classless!</Button>
</ClassNameConfigurator>

Inspect the elements in the following demo to see the difference:

{/* The built-in classes (MuiSwitch-root, Mui-checked, etc.) are enabled by default, 
    even though they are not used */}
<Switch slots={slots} {...switch1A11yProps} />

<ClassNameConfigurator disableDefaultClasses>
  {/* ClassNameConfigurator removes the built-in classes,
      leaving only the one generated by Emotion */}
  <Switch slots={slots} {...switch2A11yProps} />
</ClassNameConfigurator>

{/* The built-in classes (MuiSwitch-root, Mui-checked, etc.) are enabled by default, 
    even though they are not used */}
<Switch slots={slots} {...switch1A11yProps} />

<ClassNameConfigurator disableDefaultClasses>
  {/* ClassNameConfigurator removes the built-in classes,
      leaving only the one generated by Emotion */}
  <Switch slots={slots} {...switch2A11yProps} />
</ClassNameConfigurator>

Press Enter to start editing