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.


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

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

MUI Theme Color Palette

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>

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

MUI Custom Palette Colors
MUI Custom Palette Colors

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

***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}>
defaultValue="Custom TextField"

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.


Code Sandbox for this article with full JavaScript code.

Advanced MUI theming documentation:

Here’s an interesting Github thread addressing this topic.

Share this post:

Leave a Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.