Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 36 ยท Theming and Customization

Theme Basics and ThemeProvider

Learn how a Material UI theme works: createTheme, ThemeProvider, palette, typography, spacing and breakpoints, and how components read theme values.

Every Material UI component looks the way it does because of a theme: one plain object that stores your colors, fonts, spacing unit, breakpoints, shadows and shape. Buttons, text fields and the sx prop all read from it. If you change the theme once, the whole app changes with it. That is why theming is the first thing to learn once you can use the components.

In this lesson you will create a theme, hand it to the whole tree with ThemeProvider, read its values in your own code, and see what each part of the object controls.

Material UI itself cannot be loaded in the live editors on this site (they only have React from an import map). The real MUI code is shown read-only. The runnable examples are small stand-ins: hand-written components that use the same ideas (a theme object, a provider, a hook) so that you can experiment with the behavior.

createTheme

You build a theme with createTheme. You pass only the parts you want to change; MUI fills in every other value from its default theme.

JSX
// Real Material UI, read-only
import { createTheme } from '@mui/material/styles';

const theme = createTheme({
  palette: {
    primary: { main: '#0b6e4f' },
    secondary: { main: '#d1495b' },
  },
  typography: {
    fontFamily: '"Inter", "Helvetica", "Arial", sans-serif',
    h1: { fontSize: '2.5rem', fontWeight: 700 },
  },
  shape: { borderRadius: 12 },
  spacing: 8,
});

createTheme does not apply anything by itself. It returns an object. To use it you wrap your app:

JSX
// Real Material UI, read-only
import { ThemeProvider } from '@mui/material/styles';
import CssBaseline from '@mui/material/CssBaseline';

export default function Root() {
  return (
    <ThemeProvider theme={theme}>
      <CssBaseline />
      <App />
    </ThemeProvider>
  );
}

ThemeProvider uses React context, so every component below it sees the theme. You can nest providers: the inner theme is merged over the outer one, which is handy for a dark sidebar inside a light page. CssBaseline resets browser margins and applies the theme's background and text color to the page.

What is inside a theme

The theme object has a handful of sections that you will touch again and again.

Key What it controls Example
palette Colors: primary, secondary, error, warning, info, success, text, background, divider theme.palette.primary.main
typography Font family and the variants h1 to h6, body1, button, caption theme.typography.h4.fontSize
spacing A function that turns a number into pixels theme.spacing(2) gives 16px
breakpoints Screen widths xs, sm, md, lg, xl and helpers such as up('md') theme.breakpoints.up('md')
shape Default corner radius theme.shape.borderRadius
shadows 25 elevation shadows used by Paper, Card, AppBar theme.shadows[4]
zIndex Layers for drawers, modals, snackbars, tooltips theme.zIndex.modal
transitions Durations and easing curves theme.transitions.create('opacity')
components Per-component defaults and style overrides (see Component Overrides and Variants) components.MuiButton

Palette colors

A palette color is not one value but four: main, light, dark and contrastText. If you give only main, MUI computes the others. It also picks contrastText (black or white) so that text stays readable on top of the color. Two settings control this: contrastThreshold (default 3) and tonalOffset (default 0.2).

JSX
// Real Material UI, read-only
palette: {
  primary: { main: '#0b6e4f' }, // light, dark, contrastText are derived
  brand: { main: '#7c3aed', contrastText: '#fff' }, // a custom color needs TypeScript augmentation
}

A custom key such as brand works at runtime, but TypeScript will complain until you declare it. We cover that in Component Overrides and Variants.

Spacing

theme.spacing(n) multiplies n by the spacing unit (8px by default). The shorthand props on Box and the sx prop (p, m, gap, mt, ...) go through the same function, so sx={{ p: 2 }} is padding: 16px. Change spacing: 4 and every layout gets tighter at once.

Breakpoints

The default breakpoints are xs: 0, sm: 600, md: 900, lg: 1200 and xl: 1536. You can override them, and you can use theme.breakpoints.up('md'), down('md'), between('sm', 'lg') as media-query strings.

Reading the theme in your code

There are three ways to get at the theme.

JSX
// Real Material UI, read-only
import { useTheme, styled } from '@mui/material/styles';
import Box from '@mui/material/Box';

function Swatch() {
  const theme = useTheme(); // 1. the hook
  return <div style={{ background: theme.palette.primary.main }} />;
}

const Card = styled('div')(({ theme }) => ({ // 2. styled()
  padding: theme.spacing(3),
  borderRadius: theme.shape.borderRadius,
}));

function Panel() {
  return <Box sx={{ p: 3, bgcolor: 'primary.main', color: 'primary.contrastText' }} />; // 3. sx
}

Prefer sx and styled over useTheme when you only need styles: they are shorter and the strings like 'primary.main' are resolved for you.

Try it: a theme and a provider

Here is a stand-in. createTheme merges your options over defaults, ThemeProvider shares the result with context and useTheme reads it. The preview shows a button and a card; edit the colors in the form and watch every component change.

A createTheme and ThemeProvider stand-in

The nested card shows that a second ThemeProvider only affects its own subtree. (The real MUI merges the inner theme into the outer one; the stand-in simply replaces it to keep the code short.)

Spacing and breakpoints are functions

In the second stand-in you can see what theme.spacing and theme.breakpoints actually do. They return numbers and strings, nothing magical.

spacing() and breakpoints.up() in plain JavaScript

Good habits

  • Create the theme outside components (module scope). Creating it inside a component builds a new object on every render and re-renders everything below the provider.
  • Put CssBaseline right inside ThemeProvider once, near the root.
  • Change tokens (palette, spacing, shape) before reaching for per-component overrides. A good theme needs few overrides.
  • Use responsiveFontSizes(theme) if you want the headings to scale with the screen; it wraps a theme and returns a new one.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does createTheme return?

    createTheme returns a theme object. Nothing changes until you pass it to ThemeProvider.
  2. 2. What does sx={{ p: 2 }} produce with the default spacing?

    The spacing function multiplies the number by the spacing unit, which is 8px by default.
  3. 3. Where should you call createTheme in most apps?

    A theme created at module scope is a stable object. Creating it in the render function builds a new theme each time and re-renders consumers.
  4. 4. If you give a palette color only main, what happens to light, dark and contrastText?

    MUI derives light, dark and a readable contrastText from main, controlled by tonalOffset and contrastThreshold.

Summary

  • A theme is a plain object created with createTheme; you pass only what you want to change.
  • ThemeProvider shares it through context; CssBaseline applies page-level resets.
  • Key sections: palette, typography, spacing, breakpoints, shape, shadows, zIndex, transitions and components.
  • Read values with sx, styled or useTheme; create the theme once at module scope.

Next: Dark Mode and Color Schemes