Skip to content

Media Queries and Breakpoints

In order to make it as declarative and easy to handle media queries from JavaScript, you may be interested to use both the MediaQuery React component and the useMediaQuery React hook.

Media Queries Properties Table

UX designers are using a 12 column system during their design processes.

PixelTypeRemCustom PropertyComments
640small40em--layout-small4 columns
960medium60em--layout-medium6 columns
1152large72em--layout-large12 columns

MediaQuery component and React Hooks

Both the component and the React Hooks uses the JavaScript API matchMedia.

Re-render and performance

By using matchMedia we only render when the requested media query actually changes. So we do not need to listen to e.g. window.addEventListener('resize', ...) which is a performance waste, even with a debounce helper.

CSS similarity

It uses the same query API as CSS uses. You are able to provide your query also raw, by using e.g. query="(min-width: 60em)". But your custom queries will quickly grow and mess up your application code unnecessarily.


You can both use min and max, they are equivalent to minWidth and maxWidth.

CamelCase properties will be converted to kebab-case.


During a SSR (Server Side Render) we do not have the clients window.matchMedia. In order to make the initial render to a positive match, you can set the matchOnSSR={true} property.


Numeric values will be handled as an em unit.

useMedia hook usage

import { useMedia } from '@dnb/eufemia/shared'
function Component() {
const { isSmall, isMedium, isLarge, isSSR } = useMedia()
return isSmall ? 'true' : 'false'

To lower the possibility of CLS (Cumulative Layout Shift) on larger screens – you can make use of the isSSR property. Try to use it in combination with isLarge, because the negative CLS experience is most recognizable on larger screens:

import { useMedia } from '@dnb/eufemia/shared'
function Component() {
const { isSmall, isMedium, isLarge, isSSR } = useMedia()
return isLarge || isSSR ? 'true' : 'false'
  "isSmall": false,
  "isMedium": false,
  "isLarge": false,
  "isSSR": true,
  "innerWidth": 0

You can disable the usage of window.matchMedia by providing useMedia({ disabled: true }).

You can log the media query by providing useMedia({ log: true }).

useMediaQuery hook usage

This React Hook is a more extended version, where you can define all sorts of Media Queries.

import { useMediaQuery } from '@dnb/eufemia/shared'
// or
import useMediaQuery from '@dnb/eufemia/shared/useMediaQuery'
function Component() {
const match = useMediaQuery({
matchOnSSR: true,
when: { min: 'medium' },
return match ? 'true' : 'false'

You can disable the usage of window.matchMedia by providing useMedia({ disabled: true }).

Live example

This example uses the not property to reverse the behavior.

MediaQuery component

import { MediaQuery } from '@dnb/eufemia/shared'
// or
import MediaQuery from '@dnb/eufemia/shared/MediaQuery'

You have plenty of possibilities to mix and match:

<MediaQuery when={{ min: 'medium' }}>
matches all above medium screens
<MediaQuery when={{ screen: true, orientation: 'landscape' }}>
matches orientation landscape screens
<MediaQuery not when={{ min: 'large' }}>
matches all, but beneath large screens
<MediaQuery matchOnSSR when={{ min: 'small', max: 'medium' }}>
matches small and medium screens and during SSR
<MediaQuery when={[{ min: 'small', max: 'large' }, { print: true }]}>
matches all between small and large screens or all print media
<MediaQuery when={{ max: '60em' }}>
matches screens to a max of 60em
<MediaQuery query="(min-width: 40em) and (max-width: 72em)">
matches screens between 40em and 72em

You find the properties on this page.

Interceptor on change listener

import { onMediaQueryChange } from '@dnb/eufemia/shared/MediaQuery'
const remove = onMediaQueryChange({ min: 'medium' }, (match, event) => {
// callback
// Will remove the listeners

Use different breakpoints

It is possible to change the used breakpoint types by providing them to the Eufemia Provider.

Both the MediaQuery component and the hooks useMedia and useMediaQuery will merge and use these custom breakpoints.

NB: It should be done only temporary, because DNB should align on one set of breakpoints for best UX and consistency.

import { Provider } from '@dnb/eufemia/shared'
breakpoints: {
small: '40em',
medium: '60em',
large: '72em',
<App />

Import breakpoints into JavaScript

You get an object with the values and the types as the keys.

import { defaultBreakpoints } from '@dnb/eufemia/shared/MediaQueryUtils'

SASS / SCSS mixins

You can re-use the SASS mixins from Eufemia:

// breakpoints.scss
@import '@dnb/eufemia/style/core/utilities';
$layout-small: map-get($breakpoints, 'small');
$layout-medium: map-get($breakpoints, 'medium');
$layout-large: map-get($breakpoints, 'large');

or like this:

@import '@dnb/eufemia/style/core/utilities';
@include allBelow(large) {
/* Your CSS */
@include allAbove(small) {
/* Your CSS */

Media Queries Examples

@media screen and (max-width: 40em) {
/* small */
@media screen and (max-width: 60em) {
/* medium */
@media screen and (max-width: 72em) {
/* large */

Based of the findings of this article and this webkit bug Eufemia recommends to use em units for media query usage to meet the best overall browser support. Read more about units.

How to deal with Jest

You can mock window.matchMedia with e.g. jest-matchmedia-mock.

import MatchMediaMock from 'jest-matchmedia-mock'
const matchMedia = new MatchMediaMock()
it('your test', () => {
matchMedia.useMediaQuery('(min-width: 40em) and (max-width: 60em)')