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

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.
Resources
- Here’s how to use theme colors with the MUI Icon component
- Here’s how to Set MUI Background Color For All Components
- Test your JavaScript knowledge with these 50 challenging JavaScript questions!
Code Sandbox for this article with full JavaScript code.
Advanced MUI theming documentation: https://material-ui.com/styles/advanced/