Leveraging Media Queries in React: Building and Using the useMediaQuery Custom Hook


Web development has evolved tremendously, requiring developers to create websites that deliver a consistent user experience across a variety of devices with different screen sizes. Media queries, a feature of CSS3, have proven essential in achieving this, allowing developers to apply different styling rules based on device properties like screen width or height. In the React framework, developers can use hooks to effectively use media queries in their components, and one such hook is the 'useMediaQuery' hook.

Despite its importance, useMediaQuery is not a built-in hook in React; instead, it's a custom hook. This article provides a step-by-step tutorial on creating this custom hook from scratch, how to use it, and some of its potential use cases.

Creating the useMediaQuery Hook from Scratch

Creating a custom hook in React is similar to creating a regular JavaScript function. Here's a simple example of how you can create the useMediaQuery hook:

import { useState, useEffect } from 'react';

function useMediaQuery(query) {
  const [matches, setMatches] = useState(window.matchMedia(query).matches);

  useEffect(() => {
    const media = window.matchMedia(query);
    if (media.matches !== matches) {

    const listener = () => setMatches(media.matches);

    return () => media.removeListener(listener);
  }, [matches, query]);

  return matches;

The useMediaQuery hook takes in a media query string as a parameter. It then uses the window.matchMedia function, which returns a MediaQueryList object representing the results of the query. The matches property of this object is a boolean indicating if the document currently matches the media query.

The useState hook is used to store the state of the matches property, while the useEffect hook is used to add and remove the listener to the MediaQueryList object when the React component that uses this hook mounts or unmounts.

How to Use the useMediaQuery Hook

To use the useMediaQuery hook in your React component, simply import it and pass your media query as a string argument. Below is an example of a component that changes its layout based on the screen size:

import useMediaQuery from './useMediaQuery';

function ResponsiveComponent() {
  const isPageWide = useMediaQuery('(min-width: 800px)');

  return (
      {isPageWide ? <WideLayout /> : <NarrowLayout />}

In this example, the hook useMediaQuery takes a media query string (min-width: 800px) and returns a boolean indicating whether the page width is at least 800px. The ResponsiveComponent then renders a different layout depending on whether the page width is at least 800px or not.

Potential Use Cases

The useMediaQuery hook has numerous applications in responsive web design:

  1. Layout Adaptation: You can use this hook to switch between different layouts depending on the screen size, as shown in the example above.

  2. Dynamic Content Rendering: useMediaQuery can be used to conditionally render content. For instance, you may want to display more or less information based on the available screen size.

  3. Styling: The hook can also be useful in applying different styling rules based on the device's properties. For example, you might want to adjust font sizes, images, or colors depending on the screen width.

Unit Testing the useMediaQuery Hook

Unit testing is a crucial part of software development, ensuring that individual parts of your codebase function as expected. Testing React hooks can be a bit tricky due to their reliance on the component lifecycle and context, but libraries such as React Testing Library make this process easier.

When it comes to testing our useMediaQuery custom hook, the primary objective is to confirm that it responds correctly to different window sizes as defined by the media query input. However, since Jest (the testing framework commonly used with React) runs in a Node environment and not in a real browser, window objects, and methods like window.matchMedia() are not available by default. We'll have to mock the window object and methods like window.matchMedia() to mimic the behavior we're interested in testing.

Here's a simple unit test for useMediaQuery hook using Jest and React Testing Library:

import { renderHook } from '@testing-library/react-hooks';
import useMediaQuery from './useMediaQuery';

describe('useMediaQuery', () => {
  let matchMedia;

  beforeEach(() => {
    matchMedia = window.matchMedia;
    window.matchMedia = jest.fn().mockImplementation(query => ({
      matches: query.includes('min-width'),
      addListener: jest.fn(),
      removeListener: jest.fn(),

  afterEach(() => {
    window.matchMedia = matchMedia;

  it('returns true for matchMedia queries that contain "min-width"', () => {
    const { result } = renderHook(() => useMediaQuery('(min-width: 800px)'));

  it('returns false for matchMedia queries that do not contain "min-width"', () => {
    const { result } = renderHook(() => useMediaQuery('(max-width: 800px)'));

In this example, we're using renderHook from the React Testing Library to test the useMediaQuery hook. Before each test, we replace window.matchMedia with a mocked function that returns an object mimicking the MediaQueryList object. This mock checks if the query string includes 'min-width', returning true if it does and false otherwise. This allows us to simulate different media query conditions for testing our hook.

After each test, we restore the original window.matchMedia function to maintain the isolation of our tests. Our test cases then confirm that the hook correctly interprets media queries with 'min-width' and 'max-width', providing a solid foundation for more complex test scenarios.

Remember, these tests are quite simplified and specific to our mock implementation. In a more realistic scenario, you might use a library like jest-matchmedia-mock for more thorough and reliable matchMedia mocking.


With the proliferation of different devices, creating responsive designs has become a necessity for any web developer. The useMediaQuery hook is an excellent tool that allows for dynamic, responsive designs in React applications. It provides a flexible and straightforward way to adapt to different screen sizes and device capabilities, thereby improving the overall user experience.

By creating and utilizing the useMediaQuery custom hook, you can effectively adapt your UI to the user's environment. This dynamic responsiveness increases your website's usability and enhances its aesthetic appeal across various devices. Whether it's for adjusting layouts, dynamically rendering content, or applying specific styling rules, the useMediaQuery hook is a robust solution that every React developer should have in their toolkit.

Just as importantly, creating this custom hook is a superb practical exercise for gaining proficiency with React's hook system, especially with useState and useEffect. Understanding these fundamental hooks and learning how to create your own custom hooks is crucial for writing clean, effective React code.

Remember, the essence of modern web development lies in ensuring a smooth and consistent user experience across all devices. With custom hooks like useMediaQuery, this task becomes less daunting, and you'll find yourself building complex, responsive UIs with less effort and more efficiency. Happy coding!