Customizing the Material-UI Theme Color Palette (MUI v5)

Material-UI is a slick and powerful component library for quickly building React apps. Material-UI’s theme palette is the foundation for uniquely theming your MUI components so that your app has a distinct “look and feel”. However, it can be challenging to extend the palette to fit your app’s distinct needs.

***UPDATED FOR MUI v5

In this article, I will cover:

Basic palette usage:

listing of common palette options
overriding existing palette colors

Advanced palette usage:

adding new categories and colors to the palette
creating a component that uses the new palette option

Table of Contents hide

1 Basic Palette Usage

2 How to Use MUI Theme with Custom Colors and Theme Provider

3 Custom MUI Theme Colors (Advanced)

4 When Do We Use the MUI Theme?

4.1 Resources

Code Sandbox link is in the Resources section.

Basic Palette Usage

The default theme palette comes with a handful of preset categories. A few examples:

primary
secondary
error
warning

Within most of these categories, the color options are:

light
main
dark
contrast text

Take a look at the complete list of categories and colors here (screenshot below).

Material-UI components are pre-set to use certain categories and colors for text, borders, background color, and so on. It’s a clever system; if you create a custom palette, you can have an instantly customized color scheme.

How to Use MUI Theme with Custom Colors and Theme Provider

If you need to create a new theme, it is as simple as this customization:

//MUI v5 code:
import * as React from "react";
import Button from "@mui/material/Button";
import { createTheme, ThemeProvider } from "@mui/material/styles";

const customTheme = createTheme({
  palette: {
    primary: {
      light: "#112233",
      main: "#445566",
      dark: "#778899",
      contrastText: "#fff"
    },
    secondary: {
      light: "#f0e6e6",
      main: "#c93434",
      dark: "#3c3c3c",
      contrastText: "#000"
    }
  }
});

export default function BasicButtons() {
  return (
    <ThemeProvider theme={customTheme}>
      <Button variant="contained">Contained</Button>
    </ThemeProvider>
  );
}

If you wanted the MUI v4 code, import createMuiTheme instead of createTheme. The ThemeProvider import is different as well.

import { createMuiTheme } from '@material-ui/core/styles';
import { ThemeProvider } from "@material-ui/core/styles";

Any Buttons wrapped in a StyleProvider using these theme colors will now look like this:

MUI Themed Button

Set whatever hex values you like (but whatever you do, don’t use the boring colors I just picked).

With the basics out of the way, let’s talk about some fun stuff: adding new categories to the palette and using them in a component custom-built to use the new palette option.

Custom MUI Theme Colors (Advanced)

Here’s a TextField that we will create. It is styled with a new category of colors I created on the MUI Theme Palette:

Here’s the new palette category called ‘optional’. This uses MUI v4 imports, refer to the example above for v5 imports.

import { createMuiTheme } from '@material-ui/core/styles';

const customTheme = createMuiTheme({
  palette: {
    optional: {
      main: '#376a99',
      contrastText: '#d0e4f7'
    }
  }
});

It is as simple as that to create a new theme. It isn’t obvious from the above code, but this new theme did not override existing categories such as ‘primary’ and ‘secondary’. Those categories are still accessible to any components using customTheme.

To use customTheme, simply wrap any component in a ThemeProvider and pass customTheme to the ThemeProvider. I will show an example of this shortly.

Here’s a custom TextField component created using Styled Components:

import { withStyles } from '@material-ui/core/styles';

const StyledTextField = withStyles((theme) => ({
  root: {
    backgroundColor: theme.palette.optional.main,
    margin: theme.spacing(2),
    width: 400,
    '& .MuiInputBase-root': {
      color: theme.palette.optional.contrastText
    }
  }
}))(TextField);

***Update for MUI v5: Try using the new MUI styled() API to create Styled Components.

Notice that the backgroundColor field and the MuiInputBase-root.color field both make use of the new palette category ‘optional’. The MuiInputBase-root.color field sets the color of default and user input text in the StyledTextField. Now we have a custom component that uses our custom palette color.

Now let’s wrap this new component in our ThemeProvider and return it:

return (
    <ThemeProvider theme={customTheme}>
      <form>
        <div>
          <StyledTextField 
            label="Custom" 
            defaultValue="Custom TextField" 
          />
        </div>
      </form>
    </ThemeProvider>
  );

Not only did we create a custom Material UI component, as a bonus we have seen how to set Material UI’s TextField text color.

The palette makes custom theming pretty slick in Material UI. We could even create another theme and nest another ThemeProvider inside the first ThemeProvider if we needed highly specific styling.

Custom themes are great to use for smaller components like AppBar or Container, but they can be used to customize larger, more uniform components such as the Table or Table Cells.

***IMPORTANT: There are actually many more options on the theme object that can be customized. Most people stop at the palette. However, you can set custom breakpoints, override component styling, change typography, shadows, and more. It’s worth a read if you want to become an expert in styling MUI components.

When Do We Use the MUI Theme?

You may not realize it, but most MUI components are making use of the default theme for their colors. Examples of components that use the primary color are AppBar and Tabs.

If you leave the default styling in place, you will wind up with an application that looks like lots of other MUI apps on the internet. Instead, consider creating a custom palette and wrapping your app at a high level so all components have access to the custom theme.

Here’s a great example of extending the theme and customizing the Typography component.