Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mui/base-ui/llms.txt

Use this file to discover all available pages before exploring further.

​
useMediaQuery

A React hook for detecting media query matches using the browser’s window.matchMedia API with support for SSR.
This utility is currently unstable and may change in future releases.

​
Import

import { useMediaQuery } from '@base-ui/react/unstable-use-media-query';

​
Hook Signature

function useMediaQuery(
  query: string,
  options: useMediaQuery.Options
): boolean

​
Parameters

​
query
string
required
The media query string to match. The @media prefix is optional and will be automatically removed if present.Example: "(min-width: 768px)" or "@media (min-width: 768px)"
​
options
useMediaQuery.Options
required
Configuration options for the media query matching behavior.

​
Options

​
options.defaultMatches
boolean | undefined
default:"false"
As window.matchMedia() is unavailable on the server, it returns a default matches during the first mount.
​
options.matchMedia
typeof window.matchMedia | undefined
You can provide your own implementation of matchMedia. This can be used for handling an iframe content window.
​
options.noSsr
boolean | undefined
default:"false"
To perform the server-side hydration, the hook needs to render twice. A first time with defaultMatches, the value of the server, and a second time with the resolved value. This double pass rendering cycle comes with a drawback: it’s slower. You can set this option to true if you use the returned value only client-side.
​
options.ssrMatchMedia
((query: string) => { matches: boolean }) | undefined
You can provide your own implementation of matchMedia, it’s used when rendering server-side.

​
Return Value

Returns true if the media query matches, false otherwise.

​
Type Definitions

​
useMediaQuery.Options

interface UseMediaQueryOptions {
  defaultMatches?: boolean | undefined;
  matchMedia?: typeof window.matchMedia | undefined;
  noSsr?: boolean | undefined;
  ssrMatchMedia?: ((query: string) => { matches: boolean }) | undefined;
}

​
Usage Examples

​
Basic Usage

import { useMediaQuery } from '@base-ui/react/unstable-use-media-query';

function MyComponent() {
  const isMobile = useMediaQuery('(max-width: 768px)', {
    defaultMatches: false,
  });
  
  return (
    <div>
      {isMobile ? 'Mobile view' : 'Desktop view'}
    </div>
  );
}

​
SSR with Custom Matching

import { useMediaQuery } from '@base-ui/react/unstable-use-media-query';

function MyComponent() {
  const isWide = useMediaQuery('(min-width: 1200px)', {
    defaultMatches: false,
    ssrMatchMedia: (query) => ({
      matches: query.includes('1200px'),
    }),
  });
  
  return <div>{isWide ? 'Wide layout' : 'Normal layout'}</div>;
}

​
Client-Side Only

import { useMediaQuery } from '@base-ui/react/unstable-use-media-query';

function MyComponent() {
  const prefersDark = useMediaQuery('(prefers-color-scheme: dark)', {
    noSsr: true,
  });
  
  return <div className={prefersDark ? 'dark' : 'light'}>Content</div>;
}

​
SSR Considerations

Since window.matchMedia() is not available on the server:
  1. Default behavior: Returns defaultMatches on first render
  2. With ssrMatchMedia: Uses custom server-side matching logic
  3. With noSsr: true: Skips server-side rendering and only evaluates client-side
The hook uses useSyncExternalStore internally to ensure proper hydration and reactivity to media query changes.

​
Browser Support

This hook relies on window.matchMedia which is supported in all modern browsers. For jsdom environments (like test runners), a defensive check ensures the hook doesn’t crash when matchMedia is unavailable.

​
Related

Build docs developers (and LLMs) love

Get started for freeTalk to us