Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 36 ยท Layout and Grid

Responsive Design and Breakpoints

Make Material UI layouts responsive: the five default breakpoints, breakpoint objects in sx, theme.breakpoints helpers, the useMediaQuery hook and custom breakpoints.

People open your app on phones, tablets, laptops and ultrawide monitors. Material UI is mobile-first: you write the layout for the smallest screen, then describe how it changes as the screen grows. This lesson collects the tools for that: the breakpoint scale, responsive values in sx, the theme.breakpoints helpers and the useMediaQuery hook.

The default breakpoints

Name Min width Typical device
xs 0px phones
sm 600px large phones, small tablets
md 900px tablets, small laptops
lg 1200px laptops, desktops
xl 1536px large desktops

Each breakpoint is a minimum: md means "900px and wider". A value for xs applies everywhere unless a bigger breakpoint overrides it, which is exactly how CSS min-width media queries behave.

Responsive values everywhere

Most layout props accept a breakpoint object. You have seen it in sx, Stack and Grid:

JSX
<Box
  sx={{
    display: 'grid',
    gridTemplateColumns: { xs: '1fr', md: '240px 1fr' },
    gap: { xs: 1, md: 3 },
    p: { xs: 2, md: 4 },
  }}
/>

<Typography variant="h3" sx={{ fontSize: { xs: '1.75rem', md: '3rem' } }}>Title</Typography>
<Container maxWidth="lg" />
<Stack direction={{ xs: 'column', md: 'row' }} spacing={{ xs: 1, md: 3 }} />

You only list the breakpoints at which something changes. Use an object with keys, not an array, when you skip breakpoints; arrays map positionally to xs, sm, md, lg, xl and are harder to read.

Breakpoint helpers in the theme

Inside styled() or an sx callback you can build media queries from the theme:

JSX
import { styled } from '@mui/material/styles';

const Sidebar = styled('aside')(({ theme }) => ({
  display: 'none',
  [theme.breakpoints.up('md')]: {        // @media (min-width:900px)
    display: 'block',
    width: 240,
  },
  [theme.breakpoints.down('sm')]: {      // @media (max-width:599.95px)
    padding: theme.spacing(1),
  },
  [theme.breakpoints.between('sm', 'lg')]: { // from sm up to (not including) lg
    opacity: 0.9,
  },
  [theme.breakpoints.only('md')]: { color: 'red' },
}));
  • up(key): this breakpoint and wider.
  • down(key): narrower than the key (so down('md') means below 900px).
  • between(start, end): from start up to but not including end.
  • only(key): exactly that range.

down is exclusive of the key: down('sm') ends at 599.95px. This trips up many people the first time.

Stand-in: breakpoints as a function

This runnable example is plain JavaScript. It shows the logic behind the helpers: how the width maps to a breakpoint name, and how a responsive object is resolved with the mobile-first rule.

JS Mobile-first resolution of responsive values

Press Run (or Ctrl + Enter) to see the console output here.

No output.

useMediaQuery

Sometimes CSS is not enough: you want to render a different component, not just different styles, on small screens (a drawer instead of a sidebar, a full-screen dialog). The useMediaQuery hook returns true when a media query matches:

JSX
import useMediaQuery from '@mui/material/useMediaQuery';
import { useTheme } from '@mui/material/styles';

function Navigation() {
  const theme = useTheme();
  const isDesktop = useMediaQuery(theme.breakpoints.up('md'));

  return isDesktop ? <Sidebar /> : <TemporaryDrawer />;
}

// Or use a plain string:
const prefersDark = useMediaQuery('(prefers-color-scheme: dark)');
const isPortrait = useMediaQuery('(orientation: portrait)');

Things to know:

  • On the first (server) render the hook returns false, because there is no screen. With SSR you can pass ssr: true options with defaultMatches, or better, avoid conditional rendering for layout and use CSS (display breakpoint objects) so the server HTML is already correct.
  • Without noSsr, the hook may re-render after hydration when the real value differs; that can flash the wrong layout. For client-only apps you can pass { noSsr: true } to read the value right away.
  • Prefer CSS (sx objects) when only styles differ, and useMediaQuery when the component tree differs.

Stand-in: useMediaQuery

The second stand-in implements a useMediaQuery hook with window.matchMedia and uses it to swap a sidebar layout for a compact one. Resize the preview across 600px to see the change.

Stand-in: a useMediaQuery hook that swaps layouts

Showing and hiding

Older MUI versions had a Hidden component. It is deprecated; use display with a breakpoint object instead, which needs no extra DOM or JavaScript:

JSX
<Box sx={{ display: { xs: 'none', md: 'block' } }}>Desktop only</Box>
<Box sx={{ display: { xs: 'block', md: 'none' } }}>Mobile only</Box>

Both elements exist in the HTML; the browser hides one. That is fine for small pieces. For heavy components, avoid rendering both (use useMediaQuery).

Custom breakpoints

You can change the scale in the theme. Whatever you define is used by sx, Grid, Container and useMediaQuery:

JSX
const theme = createTheme({
  breakpoints: {
    values: { xs: 0, sm: 480, md: 768, lg: 1024, xl: 1440 },
  },
});

TypeScript users who add new breakpoint names (such as tablet) must also augment the BreakpointOverrides interface so the keys type-check.

Responsive design checklist

  1. Design for a 360px-wide phone first.
  2. Use Stack/Grid with breakpoint objects for structure.
  3. Make touch targets at least 40 to 48px; MUI buttons and icon buttons already are.
  4. Test at 320, 600, 900 and 1200px, plus landscape phones.
  5. Prefer CSS to JavaScript for layout changes; use useMediaQuery for different components.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the md key mean in sx={{ width: { md: 400 } }}?

    Breakpoints are minimum widths in a mobile-first system.
  2. 2. theme.breakpoints.down('md') matches which widths?

    down(key) is exclusive of the key: it ends just below that breakpoint's minimum width.
  3. 3. When is useMediaQuery a better choice than responsive sx values?

    Use CSS when only styles change, and useMediaQuery when the structure changes, for example drawer versus sidebar.
  4. 4. What replaces the deprecated Hidden component?

    sx={{ display: { xs: 'none', md: 'block' } }} hides elements with CSS and no extra component.

Summary

  • MUI is mobile-first with five breakpoints: xs 0, sm 600, md 900, lg 1200, xl 1536.
  • Responsive values are objects keyed by breakpoint in sx, Stack, Grid and more.
  • theme.breakpoints.up/down/between/only build media queries in styled(); down is exclusive.
  • useMediaQuery swaps component trees; be careful with SSR flashes.
  • Hide and show with display breakpoint objects; custom breakpoints live in the theme.

Next: TextField and Text Inputs