Palette - Material UI - MUI

Skip to contentMaterial UIv7.3.8

• Getting started
• Components
• Component API
• Customization
  • How to customize
  • Overriding component structure
  • Dark mode
  • Color
  • Right-to-left
  • Shadow DOM
  • Theme
    • Default theme viewer
    • Customizing the theme
    • Creating themed components
    • Components
  • Tokens
    • Palette
    • Typography
    • Spacing
    • Shape
    • Breakpoints
    • Container queriesNew
    • Density
    • z-index
    • Transitions
  • Css variablesNew
    • Overview
    • Basic usage
    • Native color
    • Advanced configuration
  • Styles
    • Cascade layersNew
• How-to guides
• Integrations
• Experimental APIs
• Migration
• Discover more
• Design resources
• Template store

+ 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 of main
• dark: A darker shade of main
• contrastText: Text color, intended to contrast with main

Here's how Material UI's default theme defines the primary color tokens:

const primary = { main: '#1976d2', light: '#42a5f5', dark: '#1565c0', contrastText: '#fff', }; CopyCopied(or $keyC)

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.primary
• .palette.secondary
• .palette.error
• .palette.warning
• .palette.info
• .palette.success

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:

PrimarySecondaryimport { createTheme, ThemeProvider } from '@mui/material/styles'; import { lime, purple } from '@mui/material/colors'; import Button from '@mui/material/Button'; const theme = createTheme({ palette: { primary: lime, secondary: purple, }, }); export default function UsingColorObject() { return ( <ThemeProvider theme={theme}> <Button variant="contained">Primary</Button> <Button variant="contained" color="secondary" sx={{ ml: 2 }}> Secondary </Button> </ThemeProvider> ); }import { createTheme, ThemeProvider } from '@mui/material/styles'; import { lime, purple } from '@mui/material/colors'; import Button from '@mui/material/Button'; const theme = createTheme({ palette: { primary: lime, secondary: purple, }, }); export default function UsingColorObject() { return ( <ThemeProvider theme={theme}> <Button variant="contained">Primary</Button> <Button variant="contained" color="secondary" sx={{ ml: 2 }}> Secondary </Button> </ThemeProvider> ); }Press Enter to start editing

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', }, }, }); CopyCopied(or $keyC) Primary

light

main

dark

Secondary

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.

Default contrast threshold3:1WarningHigher contrast threshold4.5:1Warning

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.

This only applies when working with custom colors—it won't have any effect on the default values.

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:

Default tonal offset0.2

light

main

dark

Higher tonal offset0.5

light

main

dark

Asymmetric tonal offset{ light: 0.1, dark: 0.9 }

light

main

dark

Custom colors

Unlike default colors, tokens for custom colors are not automatically calculated.

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', }, }, }); CopyCopied(or $keyC) Ochre

light

main

dark

The supported color formats are hex, rgb, and hsl. If you want to use other formats, such as oklch, you need to enable the native color feature.

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', }, }, }); CopyCopied(or $keyC) Violet

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', }), }, }); CopyCopied(or $keyC) 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"> CopyCopied(or $keyC)

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']; } } CopyCopied(or $keyC)

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; } } CopyCopied(or $keyC)

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], }, }, }); CopyCopied(or $keyC)

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; } } CopyCopied(or $keyC)

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.1 Rule 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, }, }); CopyCopied(or $keyC)

The contrastThreshold parameter can produce counterproductive results.Please verify that the APCA color contrast is improved (WCAG 3 will use this new algorithm).

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, }, }); CopyCopied(or $keyC)

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 }, }, }, }); CopyCopied(or $keyC)

The colorSchemes API is an enhanced version of the palette API, and is the preferred API for this purpose starting from Material UI v6. If you provide both colorSchemes and palette, the latter will override any styles defined in the former.

const theme = createTheme({ palette: { primary: { main: '...', }, }, colorSchemes: { light: { // This will be replaced by the palette defined above palette: { primary: { main: '...', }, }, }, dark: { ... }, }, }); CopyCopied(or $keyC)

Dark mode

For details of how you can set up a dark mode for your theme, head to the dark mode guide.

Contents

• Color tokens
• Default colors
  • Values
  • Customization
  • Contrast threshold
  • Tonal offset
• Custom colors
  • Provide tokens manually
  • Generate tokens using augmentColor utility
  • Using in components
  • TypeScript
• Adding color tokens
  • TypeScript
• Non-palette colors
• Accessibility
• Picking colors
• Color schemes
• Dark mode

Become a Diamond sponsorMUI stands in solidarity with Ukraine.Search…