useMatchMedia

The useMatchMedia hook allows you to listen for changes to a specified media query and execute a callback function whenever the change event for the media query is fired.

Add the utility

CLI

npx @ivnatsr/ezreact add use-match-media

Code

JavaScript

import { useLayoutEffect, useEffect, useRef } from 'react'

export function useMatchMedia(mediaQuery, matchCallback) {
  const matchCallbackRef = useRef(matchCallback)

  useLayoutEffect(() => {
    const media = window.matchMedia(mediaQuery)

    const listener = (event) => {
      matchCallbackRef.current(event.matches)
    }

    media.addEventListener('change', listener)
    matchCallbackRef.current(media.matches)

    return () => {
      media.removeEventListener('change', listener)
    }
  }, [mediaQuery])

  useEffect(() => {
    matchCallbackRef.current = matchCallback
  })
}

TypeScript

import { useLayoutEffect, useEffect, useRef } from 'react'

export function useMatchMedia(
  mediaQuery: string,
  matchCallback: (matches: boolean) => void | Promise<void>
) {
  const matchCallbackRef = useRef(matchCallback)

  useLayoutEffect(() => {
    const media = window.matchMedia(mediaQuery)

    const listener = (event: MediaQueryListEvent) => {
      matchCallbackRef.current(event.matches)
    }

    media.addEventListener('change', listener)
    matchCallbackRef.current(media.matches)

    return () => {
      media.removeEventListener('change', listener)
    }
  }, [mediaQuery])

  useEffect(() => {
    matchCallbackRef.current = matchCallback
  })
}

Return

This hook returns void.

Parameters

• mediaQuery: A string representing the media query to match (e.g., (max-width: 600px)).
• callback: A function that will be called with a boolean argument indicating whether the media query matches. This function can also return a promise.

Example

import { useMatchMedia } from './path/to/use-match-media'

const MatchMediaExample = () => {
  const handleMatchChange = (matches) => {
    if (matches) {
      console.log('Media query matched!')
    } else {
      console.log('Media query did not match.')
    }
  }

  useMatchMedia('(max-width: 600px)', handleMatchChange)

  return <p>Check the console for media query changes.</p>
}

export default MatchMediaExample