Themed components

You can customize a component's styles, default props, and more by using its component key inside the theme.

The components key in the theme helps to achieve styling consistency across your application. However, the theme isn't tree-shakable, prefer creating new components for heavy customizations.

Theme default props

Every Material UI component has default values for each of its props. To change these default values, use the defaultProps key exposed in the theme's components key:

const theme = createTheme({
  components: {
    // Name of the component
    MuiButtonBase: {
      defaultProps: {
        // The props to change the default for.
        disableRipple: true, // No more ripple, on the whole application 💣!
      },
    },
  },
});

If you're using TypeScript and lab components, check this article to learn how to override their styles.

Theme style overrides

The theme's styleOverrides key makes it possible to potentially change every single style injected by Material UI into the DOM. This is useful if you want to apply a fully custom design system to Material UI's components.

const theme = createTheme({
  components: {
    // Name of the component
    MuiButton: {
      styleOverrides: {
        // Name of the slot
        root: {
          // Some CSS
          fontSize: '1rem',
        },
      },
    },
  },
});

Each component is composed of several different parts. These parts correspond to classes that are available to the component—see the CSS section of the component's API page for a detailed list. You can use these classes inside the styleOverrides key to modify the corresponding parts of the component.

const theme = createTheme({
  components: {
    MuiButton: {
      styleOverrides: {
        root: ({ ownerState }) => ({
          ...(ownerState.variant === 'contained' &&
            ownerState.color === 'primary' && {
              backgroundColor: '#202020',
              color: '#fff',
            }),
        }),
      },
    },
  },
});

Overrides based on props

You can pass a callback as a value in each slot of the component's styleOverrides to apply styles based on props.

The ownerState prop is a combination of public props that you pass to the component + internal state of the component.

const finalTheme = createTheme({
  components: {
    MuiSlider: {
      styleOverrides: {
        valueLabel: ({ ownerState, theme }) => ({
          ...(ownerState.orientation === 'vertical' && {
            backgroundColor: 'transparent',
            color: theme.palette.grey[500],
          }),
        }),
      },
    },
  },
});

The sx syntax (experimental)

The sx prop acts as a shortcut for defining custom styles that access the theme object. This prop lets you write inline styles using a superset of CSS. Learn more about the concept behind the sx prop and how sx differs from the styled utility.

You can use the sx prop inside the styleOverrides key to modify styles within the theme using shorthand CSS notation. This is especially handy if you're already using the sx prop with your components, because you can use the same syntax in your theme and quickly transfer styles between the two.

const finalTheme = createTheme({
  components: {
    MuiChip: {
      styleOverrides: {
        root: ({ theme }) =>
          theme.unstable_sx({
            px: 1,
            py: 0.25,
            borderRadius: 1,
          }),
        label: {
          padding: 'initial',
        },
        icon: ({ theme }) =>
          theme.unstable_sx({
            mr: 0.5,
            ml: '-2px',
          }),
      },
    },
  },
});

Specificity

If you use the theming approach to customize the components, you'll still be able to override them using the sx prop as it has a higher CSS specificity, even if you're using the experimental sx syntax within the theme.

Creating new component variants

You can use the variants key in the theme's components section to create new variants to Material UI components. These new variants can specify what styles the component should have when that specific variant prop value is applied.

The definitions are specified in an array, under the component's name. For each of them a CSS class is added to the HTML <head>. The order is important, so make sure that the styles that should win are specified last.

const theme = createTheme({
  components: {
    MuiButton: {
      variants: [
        {
          props: { variant: 'dashed' },
          style: {
            textTransform: 'none',
            border: `2px dashed ${blue[500]}`,
          },
        },
        {
          props: { variant: 'dashed', color: 'secondary' },
          style: {
            border: `4px dashed ${red[500]}`,
          },
        },
      ],
    },
  },
});

If you're using TypeScript, you'll need to specify your new variants/colors, using module augmentation.

declare module '@mui/material/Button' {
  interface ButtonPropsVariantOverrides {
    dashed: true;
  }
}

The variant props can also be defined as a callback. This is useful if you want to apply styles when using negation in the condition. In other words, applying a different style if a particular property doesn't have a specific value.

const theme = createTheme({
  components: {
    MuiButton: {
      variants: [
        {
          props: (props) =>
            props.variant === 'dashed' && props.color !== 'secondary',
          style: {
            textTransform: 'none',
            border: `2px dashed ${blue[500]}`,
          },
        },
      ],
    },
  },
});

Theme variables

Another way to override the look of all component instances is to adjust the theme configuration variables.

const theme = createTheme({
  typography: {
    button: {
      fontSize: '1rem',
    },
  },
});