Share one Material UI theme across your app with createTheme

The practical answer

If your Material UI (MUI) components use different blues, spacing scales, or font stacks, the cause is usually scattered inline styles and hardcoded CSS values. The supported fix is to create one theme object with createTheme and wrap your application in ThemeProvider. Every MUI component inside that tree then reads palette colors, typography settings, spacing values, and component overrides from that single source.

Set up a shared theme

MUI v5 and v6 use @mui/material with Emotion as the default style engine. Install the core package and its peer dependencies from your project root. No special permissions are required.

npm install @mui/material @mui/system @emotion/react @emotion/styled

Replace npm with your package manager if needed. Confirm the installed major version before copying version-specific APIs:

npm list @mui/material

Create the theme once, typically near your application entry point:

import { createTheme, ThemeProvider } from '@mui/material';
import App from './App';

const theme = createTheme({
  palette: {
    mode: 'light',
    primary: {
      main: '#1976d2',
    },
    background: {
      default: '#f5f5f5',
    },
  },
  typography: {
    fontFamily: 'Roboto, sans-serif',
    h1: {
      fontSize: '2.5rem',
      fontWeight: 700,
    },
  },
  spacing: 4,
  components: {
    MuiButton: {
      styleOverrides: {
        root: {
          textTransform: 'none',
          borderRadius: 6,
        },
      },
    },
  },
});

export default function Root() {
  return (
    
      
    
  );
}

createTheme merges your values with MUI defaults, so you only need to override the tokens that differ. Theme tokens are named values such as primary.main that represent colors, spacing, or typography settings. ThemeProvider puts that theme into React context, which is a way to pass data through the component tree without passing props manually at every level. Components such as Button, TextField, and Box can read it through useTheme.

Use theme tokens instead of hardcoded values

The sx prop resolves shorthand properties against the active theme. This keeps colors and spacing consistent even when you switch themes:

import { Box, Button } from '@mui/material';

export default function Card() {
  return (
    
      Settings
      
        Save
      
    
  );
}

Here bgcolor: 'background.default' reads the theme's background color rather than a hardcoded hex value. p: 3 resolves to theme.spacing(3), which is 12 pixels when spacing is 4. Plain HTML elements such as div do not automatically inherit MUI theme values; wrap them in Box or use the styled utility if you need theme-aware styling outside MUI components.

Override component defaults in the theme

The components key lets you change default styles for every instance of an MUI component. The example above removes uppercase text from all buttons and sets a border radius. Slot names such as root are part of MUI's internal component structure. They are stable within a major release but can change between major versions, so test overrides after upgrading MUI.

Limits and common mistakes

• Theming only covers MUI components. Standard HTML elements need sx on a Box wrapper or styled to read theme tokens.
• Do not mutate the theme object after creation. Changing theme.palette.mode at runtime does not reliably update components because the context reference stays the same. Create a new createTheme result and store it in React state to switch themes.
• Do not use useTheme outside ThemeProvider. Behavior depends on the installed MUI version and may produce a warning or fall back to the default theme. Wrap the full component tree, including routes and modals rendered outside the main DOM container.
• Do not hardcode hex colors in sx. Values such as color: '#ff0000' bypass theming and break dark-mode consistency. Use token keys such as error.main or text.secondary.

Verify the theme is applied

1. Render a Box with sx using palette tokens, such as bgcolor: 'primary.main'.
2. Open your browser's developer tools and inspect the computed styles on that element.
3. Confirm the resolved color matches the primary.main value in your theme, not a MUI default or browser default.
4. Check package.json to confirm whether your project uses MUI v5 or v6, because peer dependencies and removed legacy props differ between those versions.

If you remove ThemeProvider temporarily, MUI components should fall back to the default theme according to your installed version's documented behavior. Use that test to confirm which parts of your tree depend on your custom theme.

Version notes

This guide targets MUI v5 and v6. createTheme is stable across both, but v6 adjusted peer dependencies and removed some legacy v4 props. Check the MUI release notes for your target major version before adopting version-specific APIs or upgrading.