Customizing the Material-UI Theme Palette – Basic and Advanced Options

Create a custom-built Material-UI component that uses a custom theme palette color

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.

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.

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

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

const theme = createMuiTheme({
palette: {
primary: {
light: '#112233',
main: '#445566',
dark: '#778899',
contrastText: '#fff',
secondary: {
light: '#f0e6e6',
main: '#c93434',
dark: '#3c3c3c',
contrastText: '#000',

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

Read here to learn how to customize Material-UI theme breakpoints, overrides, shadows, and typography.

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.

Advanced Palette Usage

First, I will create a new palette category called ‘optional’:

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

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

Test your JavaScript knowledge with these 50 challenging JavaScript questions!

If you want to gain an in-depth understanding of Material-UI syntax and APIs for styling components, I recommend you read my book, Styling Material-UI Components (affiliate link). I cover the class object API, Styled Components, and overriding components using the theme. Furthermore, there are many more examples of custom component styling.

Image for post

Advanced MUI theming documentation:

An interesting thread addressing this topic:

Share this post:

Leave a Comment

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