Breakpoints

API that enables the use of breakpoints in a wide variety of contexts.

For optimal user experience, Material Design interfaces need to be able to adapt their layout at various breakpoints. Material UI uses a simplified implementation of the original specification.

The breakpoints are used internally in various components to make them responsive, but you can also take advantage of them for controlling the layout of your application through the Grid component.

Default breakpoints

Each breakpoint (a key) matches with a fixed screen width (a value):

xs, extra-small: 0px
sm, small: 600px
md, medium: 900px
lg, large: 1200px
xl, extra-large: 1536px

These values can be customized.

CSS Media Queries

CSS media queries are the idiomatic approach to make your UI responsive. The theme provides five styles helpers to do so:

theme.breakpoints.up(key)
theme.breakpoints.down(key)
theme.breakpoints.only(key)
theme.breakpoints.not(key)
theme.breakpoints.between(start, end)

In the following demo, we change the background color (red, blue & green) based on the screen width.

<span class="token keyword">const</span> <span class="token function-variable function">styles</span> <span class="token operator">=</span> <span class="token punctuation">(</span><span class="token parameter">theme</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">root</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">padding</span><span class="token operator">:</span> theme<span class="token punctuation">.</span><span class="token function">spacing</span><span class="token punctuation">(</span><span class="token number">1</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
    <span class="token punctuation">[</span>theme<span class="token punctuation">.</span>breakpoints<span class="token punctuation">.</span><span class="token function">down</span><span class="token punctuation">(</span><span class="token string">'md'</span><span class="token punctuation">)</span><span class="token punctuation">]</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">backgroundColor</span><span class="token operator">:</span> theme<span class="token punctuation">.</span>palette<span class="token punctuation">.</span>secondary<span class="token punctuation">.</span>main<span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token punctuation">[</span>theme<span class="token punctuation">.</span>breakpoints<span class="token punctuation">.</span><span class="token function">up</span><span class="token punctuation">(</span><span class="token string">'md'</span><span class="token punctuation">)</span><span class="token punctuation">]</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">backgroundColor</span><span class="token operator">:</span> theme<span class="token punctuation">.</span>palette<span class="token punctuation">.</span>primary<span class="token punctuation">.</span>main<span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token punctuation">[</span>theme<span class="token punctuation">.</span>breakpoints<span class="token punctuation">.</span><span class="token function">up</span><span class="token punctuation">(</span><span class="token string">'lg'</span><span class="token punctuation">)</span><span class="token punctuation">]</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">backgroundColor</span><span class="token operator">:</span> green<span class="token punctuation">[</span><span class="token number">500</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

down(md): red

up(md): blue

up(lg): green

<Root>
  <Typography>down(md): red</Typography>
  <Typography>up(md): blue</Typography>
  <Typography>up(lg): green</Typography>
</Root>

<Root>
  <Typography>down(md): red</Typography>
  <Typography>up(md): blue</Typography>
  <Typography>up(lg): green</Typography>
</Root>

Press Enter to start editing

JavaScript Media Queries

Sometimes, using CSS isn't enough. You might want to change the React rendering tree based on the breakpoint value, in JavaScript.

useMediaQuery hook

You can learn more on the useMediaQuery page.

Custom breakpoints

You define your project's breakpoints in the theme.breakpoints section of your theme.

theme.breakpoints.values: Default to the above values. The keys are your screen names, and the values are the min-width where that breakpoint should start.
theme.breakpoints.unit: Default to 'px'. The unit used for the breakpoint's values.
theme.breakpoints.step: Default to 5. The increment divided by 100 used to implement exclusive breakpoints. For example, { step: 5 } means that down(500) will result in '(max-width: 499.95px)'.

If you change the default breakpoints's values, you need to provide them all:

<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">createTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">breakpoints</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">values</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">xs</span><span class="token operator">:</span> <span class="token number">0</span><span class="token punctuation">,</span>
      <span class="token literal-property property">sm</span><span class="token operator">:</span> <span class="token number">600</span><span class="token punctuation">,</span>
      <span class="token literal-property property">md</span><span class="token operator">:</span> <span class="token number">900</span><span class="token punctuation">,</span>
      <span class="token literal-property property">lg</span><span class="token operator">:</span> <span class="token number">1200</span><span class="token punctuation">,</span>
      <span class="token literal-property property">xl</span><span class="token operator">:</span> <span class="token number">1536</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

Feel free to have as few or as many breakpoints as you want, naming them in whatever way you'd prefer for your project.

<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">createTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">breakpoints</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">values</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">mobile</span><span class="token operator">:</span> <span class="token number">0</span><span class="token punctuation">,</span>
      <span class="token literal-property property">tablet</span><span class="token operator">:</span> <span class="token number">640</span><span class="token punctuation">,</span>
      <span class="token literal-property property">laptop</span><span class="token operator">:</span> <span class="token number">1024</span><span class="token punctuation">,</span>
      <span class="token literal-property property">desktop</span><span class="token operator">:</span> <span class="token number">1200</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

If you are using TypeScript, you would also need to use module augmentation for the theme to accept the above values.

declare module <span class="token string">'@mui/material/styles'</span> <span class="token punctuation">{</span>
  <span class="token keyword">interface</span> <span class="token class-name">BreakpointOverrides</span> <span class="token punctuation">{</span>
    xs<span class="token operator">:</span> <span class="token boolean">false</span><span class="token punctuation">;</span> <span class="token comment">// removes the `xs` breakpoint</span>
    sm<span class="token operator">:</span> <span class="token boolean">false</span><span class="token punctuation">;</span>
    md<span class="token operator">:</span> <span class="token boolean">false</span><span class="token punctuation">;</span>
    lg<span class="token operator">:</span> <span class="token boolean">false</span><span class="token punctuation">;</span>
    xl<span class="token operator">:</span> <span class="token boolean">false</span><span class="token punctuation">;</span>
    mobile<span class="token operator">:</span> <span class="token boolean">true</span><span class="token punctuation">;</span> <span class="token comment">// adds the `mobile` breakpoint</span>
    tablet<span class="token operator">:</span> <span class="token boolean">true</span><span class="token punctuation">;</span>
    laptop<span class="token operator">:</span> <span class="token boolean">true</span><span class="token punctuation">;</span>
    desktop<span class="token operator">:</span> <span class="token boolean">true</span><span class="token punctuation">;</span>
  <span class="token punctuation">}</span>
<span class="token punctuation">}</span>

API

`theme.breakpoints.up(key) => media query`

Arguments

key (string | number): A breakpoint key (xs, sm, etc.) or a screen width number in px.

Returns

media query: A media query string ready to be used with most styling solutions, which matches screen widths greater than the screen size given by the breakpoint key (inclusive).

Examples

<span class="token keyword">const</span> <span class="token function-variable function">styles</span> <span class="token operator">=</span> <span class="token punctuation">(</span><span class="token parameter">theme</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">root</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">backgroundColor</span><span class="token operator">:</span> <span class="token string">'blue'</span><span class="token punctuation">,</span>
    <span class="token comment">// Match [md, ∞)</span>
    <span class="token comment">//       [900px, ∞)</span>
    <span class="token punctuation">[</span>theme<span class="token punctuation">.</span>breakpoints<span class="token punctuation">.</span><span class="token function">up</span><span class="token punctuation">(</span><span class="token string">'md'</span><span class="token punctuation">)</span><span class="token punctuation">]</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">backgroundColor</span><span class="token operator">:</span> <span class="token string">'red'</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

`theme.breakpoints.down(key) => media query`

Arguments

key (string | number): A breakpoint key (xs, sm, etc.) or a screen width number in px.

Returns

media query: A media query string ready to be used with most styling solutions, which matches screen widths less than the screen size given by the breakpoint key (exclusive).

Examples

<span class="token keyword">const</span> <span class="token function-variable function">styles</span> <span class="token operator">=</span> <span class="token punctuation">(</span><span class="token parameter">theme</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">root</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">backgroundColor</span><span class="token operator">:</span> <span class="token string">'blue'</span><span class="token punctuation">,</span>
    <span class="token comment">// Match [0, md)</span>
    <span class="token comment">//       [0, 900px)</span>
    <span class="token punctuation">[</span>theme<span class="token punctuation">.</span>breakpoints<span class="token punctuation">.</span><span class="token function">down</span><span class="token punctuation">(</span><span class="token string">'md'</span><span class="token punctuation">)</span><span class="token punctuation">]</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">backgroundColor</span><span class="token operator">:</span> <span class="token string">'red'</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

`theme.breakpoints.only(key) => media query`

Arguments

key (string): A breakpoint key (xs, sm, etc.).

Returns

media query: A media query string ready to be used with most styling solutions, which matches screen widths starting from the screen size given by the breakpoint key (inclusive) and stopping at the screen size given by the next breakpoint key (exclusive).

Examples

<span class="token keyword">const</span> <span class="token function-variable function">styles</span> <span class="token operator">=</span> <span class="token punctuation">(</span><span class="token parameter">theme</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">root</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">backgroundColor</span><span class="token operator">:</span> <span class="token string">'blue'</span><span class="token punctuation">,</span>
    <span class="token comment">// Match [md, md + 1)</span>
    <span class="token comment">//       [md, lg)</span>
    <span class="token comment">//       [900px, 1200px)</span>
    <span class="token punctuation">[</span>theme<span class="token punctuation">.</span>breakpoints<span class="token punctuation">.</span><span class="token function">only</span><span class="token punctuation">(</span><span class="token string">'md'</span><span class="token punctuation">)</span><span class="token punctuation">]</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">backgroundColor</span><span class="token operator">:</span> <span class="token string">'red'</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

`theme.breakpoints.not(key) => media query`

Arguments

key (string): A breakpoint key (xs, sm, etc.).

Returns

media query: A media query string ready to be used with most styling solutions, which matches screen widths stopping at the screen size given by the breakpoint key (exclusive) and starting at the screen size given by the next breakpoint key (inclusive).

Examples

<span class="token keyword">const</span> <span class="token function-variable function">styles</span> <span class="token operator">=</span> <span class="token punctuation">(</span><span class="token parameter">theme</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">root</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">backgroundColor</span><span class="token operator">:</span> <span class="token string">'blue'</span><span class="token punctuation">,</span>
    <span class="token comment">// Match [xs, md) and [md + 1, ∞)</span>
    <span class="token comment">//       [xs, md) and [lg, ∞)</span>
    <span class="token comment">//       [0px, 900px) and [1200px, ∞)</span>
    <span class="token punctuation">[</span>theme<span class="token punctuation">.</span>breakpoints<span class="token punctuation">.</span><span class="token function">not</span><span class="token punctuation">(</span><span class="token string">'md'</span><span class="token punctuation">)</span><span class="token punctuation">]</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">backgroundColor</span><span class="token operator">:</span> <span class="token string">'red'</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

`theme.breakpoints.between(start, end) => media query`

Arguments

start (string): A breakpoint key (xs, sm, etc.) or a screen width number in px.
end (string): A breakpoint key (xs, sm, etc.) or a screen width number in px.

Returns

media query: A media query string ready to be used with most styling solutions, which matches screen widths greater than the screen size given by the breakpoint key in the first argument (inclusive) and less than the screen size given by the breakpoint key in the second argument (exclusive).

Examples

<span class="token keyword">const</span> <span class="token function-variable function">styles</span> <span class="token operator">=</span> <span class="token punctuation">(</span><span class="token parameter">theme</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">root</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">backgroundColor</span><span class="token operator">:</span> <span class="token string">'blue'</span><span class="token punctuation">,</span>
    <span class="token comment">// Match [sm, md)</span>
    <span class="token comment">//       [600px, 900px)</span>
    <span class="token punctuation">[</span>theme<span class="token punctuation">.</span>breakpoints<span class="token punctuation">.</span><span class="token function">between</span><span class="token punctuation">(</span><span class="token string">'sm'</span><span class="token punctuation">,</span> <span class="token string">'md'</span><span class="token punctuation">)</span><span class="token punctuation">]</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">backgroundColor</span><span class="token operator">:</span> <span class="token string">'red'</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

Default values

You can explore the default values of the breakpoints using the theme explorer or by opening the dev tools console on this page (window.theme.breakpoints).