Palette
The palette enables you to modify the color of the components to suit your brand.
Color tokens
Palette colors are represented by four tokens:
-
main: The main shade of the color -
light: A lighter shade ofmain -
dark: A darker shade ofmain -
contrastText: Text color, intended to contrast withmain
Here's how Material UI's default theme defines the primary color tokens:
const primary = {
main: '#1976d2',
light: '#42a5f5',
dark: '#1565c0',
contrastText: '#fff',
};
See the Color documentation for details on the Material Design color system.
Default colors
The theme exposes the following default palette
colors (accessible under
theme.palette.*):
-
primary- for primary interface elements. -
secondary- for secondary interface elements. -
error- for elements that the user should be made aware of. -
warning- for potentially dangerous actions or important messages. -
info- for highlighting neutral information. -
success- for indicating the successful completion of an action that the user triggered.
See Material Design's Color System for details on color usage and guidelines.
Values
You can explore the default palette values using
the theme explorer, or by opening the dev tools console on this
page (window.theme.palette).
Primary
palette.primary.light
#42a5f5
palette.primary.main
#1976d2
palette.primary.dark
#1565c0
Secondary
palette.secondary.light
#ba68c8
palette.secondary.main
#9c27b0
palette.secondary.dark
#7b1fa2
Error
palette.error.light
#ef5350
palette.error.main
#d32f2f
palette.error.dark
#c62828
Warning
palette.warning.light
#ff9800
palette.warning.main
#ed6c02
palette.warning.dark
#e65100
Info
palette.info.light
#03a9f4
palette.info.main
#0288d1
palette.info.dark
#01579b
Success
palette.success.light
#4caf50
palette.success.main
#2e7d32
palette.success.dark
#1b5e20
The default palette uses the shades prefixed
with A (A200, etc.)
for the secondary palette color, and the
un-prefixed shades for the other palette colors.
Customization
You may override the default palette values by including a palette object as part of your theme. If any of the:
palette color objects are provided, they will replace the default ones.
This can be achieved by either using a color object or by providing the colors directly:
Using a color object
The most direct way to customize a palette color is to import and apply one or more color objects, as shown below:
Providing the colors directly
To modify each color directly, provide an object
with one or more of the color tokens. Only the
main token is required;
light, dark, and
contrastText are optional, and if
not provided, then their values are calculated
automatically:
import { createTheme } from '@mui/material/styles';
const theme = createTheme({
palette: {
primary: {
main: '#FF5733',
// light: will be calculated from palette.primary.main,
// dark: will be calculated from palette.primary.main,
// contrastText: will be calculated to contrast with palette.primary.main
},
secondary: {
main: '#E0C2FF',
light: '#F5EBFF',
// dark: will be calculated from palette.secondary.main,
contrastText: '#47008F',
},
},
});
light
main
dark
light
main
dark
Contrast threshold
The contrastText token is
calculated using the
contrastThreshold value, to
maximize the contrast between the background and
the text.
A higher contrast threshold value increases the
point at which a background color is considered
light, and thus given a dark
contrastText. Note that the
contrast threshold follows a non-linear curve,
and defaults to a value of 3 which indicates a
minimum contrast ratio of 3:1.
Tonal offset
The light and
dark tokens are calculated using
the tonalOffset value, to shift the
main color's luminance. A
higher tonal offset value will make
light tokens lighter, and
dark tokens darker.
For example, the tonal offset default value
0.2 shifts the luminance by
approximately two indexes, so if the
main token is
blue[500], then the
light token would be
blue[300] and
dark would be
blue[700].
The tonal offset value can be either a number
between 0 and 1 (which would apply to both
light and dark tokens)
or an object with light and
dark keys specified:
light
main
dark
light
main
dark
light
main
dark
Custom colors
To add custom colors, you must either provide
the tokens manually, or generate them using the
augmentColor utility:
Provide tokens manually
The most straightforward approach is to define
all tokens—main,
light, dark, and
contrastText—manually:
import { createTheme } from '@mui/material/styles';
const theme = createTheme({
palette: {
ochre: {
main: '#E3D026',
light: '#E9DB5D',
dark: '#A29415',
contrastText: '#242105',
},
},
});
light
main
dark
If you need to manipulate colors,
@mui/material/styles provides
a set of utilities
to help with this. The following example uses
the alpha() and
getContrastRatio() utilities to
define tokens using opacity:
import { createTheme, alpha, getContrastRatio } from '@mui/material/styles';
const violetBase = '#7F00FF';
const violetMain = alpha(violetBase, 0.7);
const theme = createTheme({
palette: {
violet: {
main: violetMain,
light: alpha(violetBase, 0.5),
dark: alpha(violetBase, 0.9),
contrastText: getContrastRatio(violetMain, '#fff') > 4.5 ? '#fff' : '#111',
},
},
});
light
main
dark
Generate tokens using augmentColor utility
Alternatively, you can generate the
light, dark and
contrastText tokens using the
palette's augmentColor utility,
which is the same function used for the default
palette colors. This requires creating the theme
in two steps and providing the
main token on which the other will
be based on:
import { createTheme } from '@mui/material/styles';
let theme = createTheme({
// Theme customization goes here as usual, including tonalOffset and/or
// contrastThreshold as the augmentColor() function relies on these
});
theme = createTheme(theme, {
// Custom colors created with augmentColor go here
palette: {
salmon: theme.palette.augmentColor({
color: {
main: '#FF5733',
},
name: 'salmon',
}),
},
});
light
main
dark
The contrast threshold and tonal offset values will apply for the colors defined using this utility.
Using in components
After adding a custom color, you will be able to use it in components just like you do with default palette colors:
<Button color="custom">
TypeScript
If you're using TypeScript, then you need to use module augmentation for custom colors.
To add a custom color to the palette, you must
add it to the Palette and
PaletteOptions interfaces:
declare module '@mui/material/styles' {
interface Palette {
custom: Palette['primary'];
}
interface PaletteOptions {
custom?: PaletteOptions['primary'];
}
}
To use a custom color for the
color prop of a component, you must
add it to the component's
PropsColorOverrides interface. The
example below shows how to do this with a Button
component:
declare module '@mui/material/Button' {
interface ButtonPropsColorOverrides {
custom: true;
}
}
Adding color tokens
To add a new color token, include it in the color's object as follows:
import { createTheme } from '@mui/material/styles';
import { blue } from '@mui/material/colors';
const theme = createTheme({
palette: {
primary: {
light: blue[300],
main: blue[500],
dark: blue[700],
darker: blue[900],
},
},
});
light
main
dark
darker
TypeScript
If you're using TypeScript, then you'll
need to use
module augmentation
to add the new color token to the
PaletteColor and
SimplePaletteColorOptions
interfaces as follows:
declare module '@mui/material/styles' {
interface PaletteColor {
darker?: string;
}
interface SimplePaletteColorOptions {
darker?: string;
}
}
Non-palette colors
To learn how to add colors outside of
theme.palette, see
Theming—Custom variables.
Accessibility
To meet the minimum contrast of at least 4.5:1 as defined in WCAG 2.2 Success Criterion 1.4.3, create a custom theme with a contrast threshold value of 4.5 as follows:
import { createTheme } from '@mui/material/styles';
const theme = createTheme({
palette: {
contrastThreshold: 4.5,
},
});
Windows High Contrast mode
To improve component visibility in Windows High
Contrast mode (also known as
Forced Colors), use the
enhanceHighContrast theme enhancer,
starting from v9.1.0. It accepts a fully-created
theme and returns an enhanced version of it with
@media (forced-colors: active)
overrides applied to the affected components.
import { createTheme, enhanceHighContrast } from '@mui/material/styles';
const theme = enhanceHighContrast(createTheme());
By default, it uses the
CSS system color keywords
(Highlight,
HighlightText,
ButtonBorder, etc.). You can
override individual tokens with other
system colors
to match your brand or design requirements. When
overriding paired tokens, choose values that the
browser guarantees to contrast with each other —
for example SelectedItem is always
paired with SelectedItemText, and
Highlight with
HighlightText:
import { createTheme, enhanceHighContrast } from '@mui/material/styles';
const theme = enhanceHighContrast(createTheme(), {
// Use the system's selection colors for active or toggled controls.
activeBackground: 'SelectedItem',
activeText: 'SelectedItemText',
});
The following tokens are available, showing how your browser resolves each system color keyword in the current environment:
| Token | Default | Description |
|---|---|---|
disabled
|
GrayText
|
Color for disabled elements |
error
|
ActiveText
|
Color for error states |
selectedBackground
|
SelectedItem
|
Background color for selected items |
selectedText
|
SelectedItemText
|
Text color on selected items |
activeBackground
|
Highlight
|
Background color for active or toggled controls |
activeText
|
HighlightText
|
Text color on active or toggled controls |
buttonBorder
|
ButtonBorder
|
Border color for interactive controls |
buttonText
|
ButtonText
|
Text and icon color on buttons |
canvas
|
Canvas
|
Background color for the page or canvas |
Picking colors
Need inspiration? The Material Design team has built an palette configuration tool to help you.
Color schemes
To add both built-in light and dark color
schemes without creating separate themes, use
the
colorSchemes: { light: true, dark: true
}. This generates the default tokens for both
color schemes:
import { createTheme } from '@mui/material/styles';
const theme = createTheme({
colorSchemes: {
light: true,
dark: true,
},
});
To override the default tokens for each color scheme, use the same palette object as shown below:
const theme = createTheme({
colorSchemes: {
light: {
palette: {
primary: {
main: '#FF5733',
},
// ...other tokens
},
},
dark: {
palette: {
primary: {
main: '#E0C2FF',
},
// ...other tokens
},
},
},
});
Dark mode
For details of how you can set up a dark mode for your theme, head to the dark mode guide.