Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 36 ยท Theming and Customization

Component Overrides and Variants

Customize every Material UI component from the theme: defaultProps, styleOverrides, custom variants, TypeScript module augmentation, slots and slotProps.

Changing the palette gets you far, but real design systems need more: every Button should be uppercase-free and slightly rounder, every TextField should be small by default, and you want a new variant="soft". Material UI lets you do all of that in the theme, under the components key, instead of repeating sx on every instance.

Material UI itself cannot run in the live editors on this site. Real MUI code is read-only; the runnable examples use stand-in components that apply theme overrides the same way, so you can see the mechanism.

Three tools in the components key

Each component has a theme key that starts with Mui (MuiButton, MuiTextField, MuiCard...). Under it you can set:

Option Purpose
defaultProps Props applied when the caller does not set them
styleOverrides CSS for the component's parts (slots), such as root or label
variants Extra named styles chosen by props
JSX
// Real Material UI, read-only
import { createTheme } from '@mui/material/styles';

const theme = createTheme({
  components: {
    MuiButton: {
      defaultProps: {
        disableElevation: true,
        size: 'medium',
      },
      styleOverrides: {
        root: {
          textTransform: 'none',
          borderRadius: 999,
          fontWeight: 600,
        },
        containedPrimary: ({ theme }) => ({
          '&:hover': { backgroundColor: theme.palette.primary.dark },
        }),
      },
    },
    MuiTextField: {
      defaultProps: { size: 'small', variant: 'outlined', fullWidth: true },
    },
    MuiCard: {
      styleOverrides: {
        root: ({ theme }) => ({ border: `1px solid ${theme.palette.divider}` }),
      },
    },
  },
});

defaultProps

They run first and can be overridden at the call site. Use them for settings you would otherwise repeat in a hundred places (disableRipple, size, fullWidth, elevation). A common one is turning off the ripple effect or changing Link to underline="hover".

styleOverrides

The keys are the component's slots. The API page for each component lists them under "CSS" (root, label, outlined, containedPrimary...). The value can be an object or a function that receives { theme, ownerState }. ownerState holds the props the component was rendered with, so you can write conditional styles:

JSX
// Real Material UI, read-only
MuiChip: {
  styleOverrides: {
    root: ({ ownerState, theme }) => ({
      ...(ownerState.color === 'success' && {
        backgroundColor: theme.palette.success.light,
      }),
    }),
  },
},

Custom variants

variants adds your own value for an existing prop, such as variant="dashed", and gives it styles:

JSX
// Real Material UI, read-only
MuiButton: {
  variants: [
    {
      props: { variant: 'dashed' },
      style: ({ theme }) => ({
        textTransform: 'none',
        border: `2px dashed ${theme.palette.primary.main}`,
      }),
    },
    {
      props: { variant: 'dashed', color: 'secondary' },
      style: ({ theme }) => ({ border: `2px dashed ${theme.palette.secondary.main}` }),
    },
  ],
},

The props object is a match: every key must equal the component's prop. Later variants win when several match, so write the general one first.

TypeScript: module augmentation

TypeScript only allows variant values it knows about. Tell it about your new one by augmenting the module:

TSX
// Real Material UI, read-only (a .d.ts or any .ts file)
declare module '@mui/material/Button' {
  interface ButtonPropsVariantOverrides {
    dashed: true;
  }
}

declare module '@mui/material/styles' {
  interface Palette {
    brand: Palette['primary'];
  }
  interface PaletteOptions {
    brand?: PaletteOptions['primary'];
  }
}
declare module '@mui/material/Button' {
  interface ButtonPropsColorOverrides {
    brand: true;
  }
}

After this, <Button variant="dashed" color="brand"> type-checks. Without it, the code still works at runtime, but the compiler complains.

Try it: defaultProps, styleOverrides and a variant

The stand-in Button reads its overrides from a theme. Use the form to edit the theme and see what each option does. The "dashed" variant is created purely in the theme.

A theme that customizes Button

Slots and slotProps

Many MUI components are built from several inner parts called slots: an Autocomplete has an input, a popper and a listbox; a TextField has an input, a label and a helper text. Since v6 the way to configure these is two props, slots (replace the component used for a part) and slotProps (pass props to it):

JSX
// Real Material UI, read-only
<TextField
  label="Email"
  slotProps={{
    input: { startAdornment: <InputAdornment position="start">@</InputAdornment> },
    htmlInput: { maxLength: 80, 'data-testid': 'email' },
    inputLabel: { shrink: true },
  }}
/>

<Autocomplete
  options={options}
  slots={{ paper: MyPaper }}
  slotProps={{ listbox: { sx: { maxHeight: 240 } } }}
/>

Older code uses inputProps, InputProps, PaperProps and so on. These are deprecated in favor of slotProps; read the component's API page to see which slots exist.

Try it: slots in a stand-in

A Field component exposes slotProps for its label, input and helper text, and lets you swap the input slot for your own component.

slots and slotProps in a stand-in Field

Customization levels

MUI documents five levels, from narrow to wide. Use the narrowest that fits.

  1. One instance: the sx prop.
  2. A reusable component: wrap it with styled().
  3. Every instance of one component: components in the theme.
  4. A global rule: CssBaseline overrides, or GlobalStyles.
  5. Design tokens: palette, typography, spacing.

See The sx Prop and styled() for levels 1 and 2.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where do theme-level overrides for every Button live?

    Each MUI component has a Mui-prefixed key under components, such as MuiButton, with defaultProps, styleOverrides and variants.
  2. 2. When both a theme defaultProp and a call-site prop are set, which wins?

    defaultProps only fill in missing props. An explicit prop on the element overrides them.
  3. 3. What is module augmentation used for with a custom variant?

    The variant works at runtime from the theme alone. The augmentation only teaches the type system about it.
  4. 4. Which prop is the modern way to pass props to the inner input of a TextField?

    Since v6 slotProps replaces the older InputProps and inputProps for configuring inner parts.

Summary

  • Put app-wide component settings under theme.components.MuiXxx: defaultProps, styleOverrides and variants.
  • Style overrides can be functions of { theme, ownerState }.
  • Add custom variants and colors in the theme and declare them to TypeScript with module augmentation.
  • Use slots and slotProps to replace or configure inner parts of a component.
  • Pick the narrowest customization level: sx, styled, theme overrides, global styles, tokens.

Next: App Bar and Drawer Navigation