useMediaQuery

The useMediaQuery hook allows you to programmatically detect whether a CSS media query matches the current viewport, with full support for server-side rendering. Note: This hook is currently unstable and its API may change in future versions.

Import

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

Usage

Basic usage to detect viewport width:

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

function MyComponent() {
  const isMobile = useMediaQuery('(max-width: 768px)', {});

  return (
    <div>
      {isMobile ? 'Mobile view' : 'Desktop view'}
    </div>
  );
}

Media query syntax

You can use any valid CSS media query. The @media prefix is optional:

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

function MyComponent() {
  // All of these are valid:
  const matches1 = useMediaQuery('(min-width: 600px)', {});
  const matches2 = useMediaQuery('@media (min-width: 600px)', {});
  const matches3 = useMediaQuery('(orientation: portrait)', {});
  const matches4 = useMediaQuery('(prefers-color-scheme: dark)', {});

  return null;
}

Server-side rendering

Provide a default match value for server-side rendering:

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

function MyComponent() {
  const isMobile = useMediaQuery('(max-width: 768px)', {
    defaultMatches: false,
  });

  return (
    <div>
      {isMobile ? 'Mobile' : 'Desktop'}
    </div>
  );
}

API Reference

Parameters

`query`

Type: string
Required

The media query string to match. The @media prefix is optional and will be stripped if provided.

`options`

Type: UseMediaQueryOptions
Required

Configuration options for the hook.

Options

`defaultMatches`

Type: boolean
Default: false
Optional

As window.matchMedia() is unavailable on the server, the hook returns this value during the first mount. This enables hydration without mismatches.

`matchMedia`

Type: typeof window.matchMedia
Optional

Custom implementation of matchMedia. Useful for handling iframe content windows. Example:

const matches = useMediaQuery('(min-width: 600px)', {
  matchMedia: iframe.contentWindow.matchMedia,
});

`noSsr`

Type: boolean
Default: false
Optional

Skips the double-pass rendering for server-side hydration. Set to true if you use the returned value only client-side, which improves performance by avoiding the extra render.

`ssrMatchMedia`

Type: (query: string) => { matches: boolean }
Optional

Custom implementation of matchMedia for server-side rendering. Allows you to determine matches on the server based on request headers or other server-side context. Example:

function ssrMatchMedia(query: string) {
  // Determine matches based on user agent or other server context
  return { matches: query.includes('max-width: 768px') };
}

const matches = useMediaQuery('(max-width: 768px)', {
  ssrMatchMedia,
});

Return Value

Returns true if the media query matches the current environment, false otherwise.

Use Cases

Responsive components

Create components that adapt to different screen sizes:

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

function ResponsiveMenu() {
  const isMobile = useMediaQuery('(max-width: 768px)', {
    defaultMatches: false,
  });

  return isMobile ? <MobileMenu /> : <DesktopMenu />;
}

Theme detection

Detect user’s color scheme preference:

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

function ThemeProvider({ children }) {
  const prefersDark = useMediaQuery('(prefers-color-scheme: dark)', {
    defaultMatches: false,
  });

  return (
    <div className={prefersDark ? 'dark-theme' : 'light-theme'}>
      {children}
    </div>
  );
}

Conditional feature loading

Load features based on device capabilities:

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

function VideoPlayer() {
  const canAutoplay = useMediaQuery('(prefers-reduced-motion: no-preference)', {
    defaultMatches: true,
  });

  return (
    <video autoPlay={canAutoplay}>
      <source src="video.mp4" />
    </video>
  );
}

Multiple breakpoints

Track multiple breakpoints simultaneously:

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

function useBreakpoint() {
  const isXs = useMediaQuery('(max-width: 575px)', { defaultMatches: false });
  const isSm = useMediaQuery('(min-width: 576px) and (max-width: 767px)', { defaultMatches: false });
  const isMd = useMediaQuery('(min-width: 768px) and (max-width: 991px)', { defaultMatches: false });
  const isLg = useMediaQuery('(min-width: 992px) and (max-width: 1199px)', { defaultMatches: false });
  const isXl = useMediaQuery('(min-width: 1200px)', { defaultMatches: false });

  return { isXs, isSm, isMd, isLg, isXl };
}

Server-side device detection

Use request headers to determine matches on the server:

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

function MyComponent({ userAgent }: { userAgent: string }) {
  const isMobile = useMediaQuery('(max-width: 768px)', {
    ssrMatchMedia: (query) => ({
      matches: /mobile/i.test(userAgent),
    }),
  });

  return (
    <div>
      {isMobile ? 'Mobile device' : 'Desktop device'}
    </div>
  );
}

Getting Started

Handbook

Inputs

Data Display

Navigation

Overlays

Forms

Layout

Utilities

useMediaQuery

useMediaQuery

Import

Usage

Media query syntax

Server-side rendering

API Reference

Parameters

`query`

`options`

Options

`defaultMatches`

`matchMedia`

`noSsr`

`ssrMatchMedia`

Return Value

Use Cases

Responsive components

Theme detection

Conditional feature loading

Multiple breakpoints

Server-side device detection

​useMediaQuery

​Import

​Usage

​Media query syntax

​Server-side rendering

​API Reference

​Parameters

​query

​options

​Options

​defaultMatches

​matchMedia

​noSsr

​ssrMatchMedia

​Return Value

​Use Cases

​Responsive components

​Theme detection

​Conditional feature loading

​Multiple breakpoints

​Server-side device detection

useMediaQuery

Import

Usage

Media query syntax

Server-side rendering

API Reference

Parameters

`query`

`options`

Options

`defaultMatches`

`matchMedia`

`noSsr`

`ssrMatchMedia`

Return Value

Use Cases

Responsive components

Theme detection

Conditional feature loading

Multiple breakpoints

Server-side device detection