Skip to main content

​
Color Palette Customization

The palette is the foundation of your application’s color system. Material UI provides a comprehensive palette structure that supports light and dark modes.

​
Default Palette Colors

Material UI comes with default color values for light mode: Light Mode Defaults:
  • Primary: blue[700] (#1976d2)
  • Secondary: purple[500] (#9c27b0)
  • Error: red[700] (#d32f2f)
  • Warning: #ed6c02 (optimized for 3:1 contrast)
  • Info: lightBlue[700] (#0288d1)
  • Success: green[800] (#2e7d32)
Dark Mode Defaults:
  • Primary: blue[200] (#90caf9)
  • Secondary: purple[200] (#ce93d8)
  • Error: red[500] (#f44336)
  • Warning: orange[400] (#ffa726)
  • Info: lightBlue[400] (#29b6f6)
  • Success: green[400] (#66bb6a)

​
Palette Structure

Each color in the palette has the following structure: 
interface PaletteColor {
  light: string;    // Lighter variant
  main: string;     // Main color (required)
  dark: string;     // Darker variant
  contrastText: string; // Text color that contrasts with main
}

​
Basic Customization

import { createTheme } from '@mui/material/styles';
import { red, green } from '@mui/material/colors';

const theme = createTheme({
  palette: {
    primary: {
      main: '#1976d2',
    },
    secondary: {
      main: '#dc004e',
    },
    error: {
      main: red[700],
    },
  },
});

​
Using Material UI Colors

Import pre-defined color palettes: 
import { 
  blue, purple, red, orange, green, 
  lightBlue, deepOrange, grey 
} from '@mui/material/colors';

const theme = createTheme({
  palette: {
    primary: blue,
    secondary: purple,
  },
});

​
Available Color Palettes

Each color has shades from 50 to 900, plus accent shades (A100, A200, A400, A700): Blue: 
blue[50]  // '#e3f2fd'
blue[100] // '#bbdefb'
blue[200] // '#90caf9'
blue[300] // '#64b5f6'
blue[400] // '#42a5f5'
blue[500] // '#2196f3'
blue[600] // '#1e88e5'
blue[700] // '#1976d2'
blue[800] // '#1565c0'
blue[900] // '#0d47a1'
blue.A100 // '#82b1ff'
blue.A200 // '#448aff'
blue.A400 // '#2979ff'
blue.A700 // '#2962ff'
Grey: 
grey[50]  // '#fafafa'
grey[100] // '#f5f5f5'
grey[200] // '#eeeeee'
grey[300] // '#e0e0e0'
grey[400] // '#bdbdbd'
grey[500] // '#9e9e9e'
grey[600] // '#757575'
grey[700] // '#616161'
grey[800] // '#424242'
grey[900] // '#212121'

​
Common Colors

import { common } from '@mui/material/colors';

common.black // '#000'
common.white // '#fff'

​
Auto-generated Variants

When you only provide main, Material UI automatically generates light and dark variants: 
const theme = createTheme({
  palette: {
    primary: {
      main: '#1976d2',
      // light and dark are auto-generated
    },
  },
});

// Generated values:
// light: lighten(main, tonalOffset)
// dark: darken(main, tonalOffset * 1.5)

​
Tonal Offset

Control how light and dark variants are generated: 
const theme = createTheme({
  palette: {
    primary: { main: '#1976d2' },
    tonalOffset: 0.2, // Default value
  },
});

// Or use separate values for light and dark:
const theme = createTheme({
  palette: {
    primary: { main: '#1976d2' },
    tonalOffset: {
      light: 0.8,
      dark: 0.5,
    },
  },
});

​
Text Colors

Light Mode: 
text: {
  primary: 'rgba(0, 0, 0, 0.87)',
  secondary: 'rgba(0, 0, 0, 0.6)',
  disabled: 'rgba(0, 0, 0, 0.38)',
}
Dark Mode: 
text: {
  primary: '#fff',
  secondary: 'rgba(255, 255, 255, 0.7)',
  disabled: 'rgba(255, 255, 255, 0.5)',
}

​
Background Colors

Light Mode: 
background: {
  paper: '#fff',
  default: '#fff',
}
Dark Mode: 
background: {
  paper: '#121212',
  default: '#121212',
}

​
Action Colors

Light Mode: 
action: {
  active: 'rgba(0, 0, 0, 0.54)',
  hover: 'rgba(0, 0, 0, 0.04)',
  hoverOpacity: 0.04,
  selected: 'rgba(0, 0, 0, 0.08)',
  selectedOpacity: 0.08,
  disabled: 'rgba(0, 0, 0, 0.26)',
  disabledBackground: 'rgba(0, 0, 0, 0.12)',
  disabledOpacity: 0.38,
  focus: 'rgba(0, 0, 0, 0.12)',
  focusOpacity: 0.12,
  activatedOpacity: 0.12,
}
Dark Mode: 
action: {
  active: '#fff',
  hover: 'rgba(255, 255, 255, 0.08)',
  hoverOpacity: 0.08,
  selected: 'rgba(255, 255, 255, 0.16)',
  selectedOpacity: 0.16,
  disabled: 'rgba(255, 255, 255, 0.3)',
  disabledBackground: 'rgba(255, 255, 255, 0.12)',
  disabledOpacity: 0.38,
  focus: 'rgba(255, 255, 255, 0.12)',
  focusOpacity: 0.12,
  activatedOpacity: 0.24,
}

​
Divider Color

Light Mode: rgba(0, 0, 0, 0.12) Dark Mode: rgba(255, 255, 255, 0.12)

​
Contrast Threshold

The contrastThreshold determines when to use light vs dark text: 
const theme = createTheme({
  palette: {
    contrastThreshold: 3, // Default (WCAG AA)
    // Set to 7 for WCAG AAA compliance
  },
});

​
Augment Color Function

Manually augment colors with the augmentColor helper: 
const theme = createTheme({
  palette: {
    primary: { main: '#1976d2' },
  },
});

const customColor = theme.palette.augmentColor({
  color: { main: '#ff5722' },
  name: 'tertiary',
});

// Returns: { light, main, dark, contrastText }

​
Get Contrast Text

Get text color that contrasts with a background: 
const theme = createTheme();

const textColor = theme.palette.getContrastText('#1976d2');
// Returns: '#fff' (white text on blue background)

​
Source Reference

The palette implementation can be found at:
  • packages/mui-material/src/styles/createPalette.js:211
  • Color definitions: packages/mui-material/src/colors/
  • Light mode defaults: packages/mui-material/src/styles/createPalette.js:12
  • Dark mode defaults: packages/mui-material/src/styles/createPalette.js:55

Build docs developers (and LLMs) love

Get started for freeTalk to us