Dark mode

Material UI comes with two palette modes: light (the default) and dark.

Dark mode by default

You can make your application use the dark theme as the default—regardless of the user's preference—by adding mode: 'dark' to the createTheme helper:

import { ThemeProvider, createTheme, CssBaseline } from '@mui/material/styles';

const darkTheme = createTheme({
  palette: {
    mode: 'dark',
  },
});

function App() {
  return (
    <ThemeProvider theme={darkTheme}>
      <CssBaseline />
      <main>This app is using the dark mode</main>
    </ThemeProvider>
  );
}

export default App;

Adding mode: 'dark' to the createTheme helper modifies several palette values, as shown in the following demo:

Typography

palette.text.primary

#fff

palette.text.secondary

rgba(255, 255, 255, 0.7)

palette.text.disabled

rgba(255, 255, 255, 0.5)

Buttons

palette.action.active

#fff

palette.action.hover

rgba(255, 255, 255, 0.08)

palette.action.selected

rgba(255, 255, 255, 0.16)

palette.action.disabled

rgba(255, 255, 255, 0.3)

palette.action.disabledBackground

rgba(255, 255, 255, 0.12)

Background

palette.background.default

#121212

palette.background.paper

#121212

Divider

palette.divider

rgba(255, 255, 255, 0.12)

Typography

palette.text.primary

rgba(0, 0, 0, 0.87)

palette.text.secondary

rgba(0, 0, 0, 0.6)

palette.text.disabled

rgba(0, 0, 0, 0.38)

Buttons

palette.action.active

rgba(0, 0, 0, 0.54)

palette.action.hover

rgba(0, 0, 0, 0.04)

palette.action.selected

rgba(0, 0, 0, 0.08)

palette.action.disabled

rgba(0, 0, 0, 0.26)

palette.action.disabledBackground

rgba(0, 0, 0, 0.12)

Background

palette.background.default

#fff

palette.background.paper

#fff

Divider

palette.divider

rgba(0, 0, 0, 0.12)

Adding <CssBaseline /> inside of the <ThemeProvider> component will also enable dark mode for the app's background.

Dark mode with a custom palette

To use custom palettes for light and dark modes, you can create a function that will return the correct palette depending on the selected mode, as shown here:

const getDesignTokens = (mode: PaletteMode) => ({
  palette: {
    mode,
    ...(mode === 'light'
      ? {
          // palette values for light mode
          primary: amber,
          divider: amber[200],
          text: {
            primary: grey[900],
            secondary: grey[800],
          },
        }
      : {
          // palette values for dark mode
          primary: deepOrange,
          divider: deepOrange[700],
          background: {
            default: deepOrange[900],
            paper: deepOrange[900],
          },
          text: {
            primary: '#fff',
            secondary: grey[500],
          },
        }),
  },
});

You can see on the example that there are different colors used based on whether the mode is light or dark. The next step is to use this function when creating the theme.

export default function App() {
  const [mode, setMode] = React.useState<PaletteMode>('light');
  const colorMode = React.useMemo(
    () => ({
      // The dark mode switch would invoke this method
      toggleColorMode: () => {
        setMode((prevMode: PaletteMode) =>
          prevMode === 'light' ? 'dark' : 'light',
        );
      },
    }),
    [],
  );

  // Update the theme only if the mode changes
  const theme = React.useMemo(() => createTheme(getDesignTokens(mode)), [mode]);

  return (
    <ColorModeContext.Provider value={colorMode}>
      <ThemeProvider theme={theme}>
        <Page />
      </ThemeProvider>
    </ColorModeContext.Provider>
  );
}

Here is a fully working example:

This is a dark mode theme with custom palette

Toggling color mode

To give your users a way to toggle between modes, you can add React's context to a button's onClick event, as shown in the following demo:

light mode

System preference

Users might have a preference for light or dark mode that they've set through their operating system—either systemwide, or for a single user agent.

You can make use of this preference with the useMediaQuery hook and the prefers-color-scheme media query.

The following demo shows how to enable dark mode automatically by checking for the user's preference in their OS or browser settings:

import * as React from 'react';
import useMediaQuery from '@mui/material/useMediaQuery';
import { createTheme, ThemeProvider } from '@mui/material/styles';
import CssBaseline from '@mui/material/CssBaseline';

function App() {
  const prefersDarkMode = useMediaQuery('(prefers-color-scheme: dark)');

  const theme = React.useMemo(
    () =>
      createTheme({
        palette: {
          mode: prefersDarkMode ? 'dark' : 'light',
        },
      }),
    [prefersDarkMode],
  );

  return (
    <ThemeProvider theme={theme}>
      <CssBaseline />
      <Routes />
    </ThemeProvider>
  );
}