JGuang
中

useMediaQuery

useMediaQuery · Material UI

Preview
npm install @mui/material@9.4.0 @emotion/react@11.14.0 @emotion/styled@11.14.1

useMediaQuery

Observe a CSS media query using the native hook and optional SSR matching policy.

This guide covers Material UI Core with the default Emotion engine; extensions and additional demos are explicitly classified.

Use case and business boundary

A server has no browser viewport; defaultMatches/ssrMatchMedia affect hydration and noSsr is not a universal SSR fix.

Native composition and scope

Native useMediaQuery hook guide, not a visible control.

Preserve native Material UI composition and types; do not substitute JGuang UI/Base UI/Radix APIs. Example entries are not extra components.

Native installation and initialization

npm install @mui/material@9.4.0 @emotion/react@11.14.0 @emotion/styled@11.14.1

Use native npm and Emotion, not an invented JGuang UI Registry URL. Place examples inside native ThemeProvider; choose CssBaseline or ScopedCssBaseline for the project. Inspect React, existing providers, lockfile and SSR first. Never overwrite files or conceal peer conflicts. This batch verified React 19.2.8; React 18 and below require matching react-is. See the included bilingual setup guide.

Hook arguments

The first argument is a CSS media-query string or a native-theme query function; supply ThemeProvider before using the theme callback. options.defaultMatches, ssrMatchMedia, matchMedia and noSsr are native matching policy, not visible component props. A server has no viewport: use a verified estimate or accept client re-matching. Do not replace it with another system's breakpoint API.

Runnable native examples

Machine keys select example entries, not universal variant props. Native demo JSX/data stay unchanged; JGuang-authored acceptance fixtures are explicitly labelled.

  • Basic media query · SimpleMediaQuery · upstream native demo
  • Using breakpoint helpers · ThemeHelper · upstream native demo
  • Migrating from withWidth() · UseWidth · upstream native demo

Explicitly unsupported additional examples

These remain in the upstream inventory, not silently skipped or presented as working previews. Additional dependency/framework acceptance is required.

  • Using JavaScript syntax · JavaScriptMedia: json2mq
  • Server-side rendering · ServerSide: css-mediaquery

Actual usage example

Unmodified pinned native demo; copy its required local helper files together.

import useMediaQuery from '@mui/material/useMediaQuery';

export default function SimpleMediaQuery() {
  const matches = useMediaQuery('(min-width:600px)');

  return <span>{`(min-width:600px) matches: ${matches}`}</span>;
}

Example dependency boundaries

@mui/material/useMediaQuery, @mui/material/styles

Direct Icons/System/Utils example imports require their matching 9.4.0 packages. Relative data/helpers are part of the example closure, not extra components. Remote images and simulated operations do not supply a backend.

Post-install acceptance

Run strict types, production build and real interactions. Check keyboard labels/focus, disabled/error/read-only semantics where natively supported, both themes, narrow screens and reduced motion. Verify callbacks against the real host data; do not declare installation complete from copying a prompt. Initialization fixtures also require server HTML and warning-free hydration.

Source and license

https://github.com/mui/material-ui/tree/809a7717b4c050ba3f69b75300689f07c050a16e

MIT · @mui/material@9.4.0. Vendor originals and license are preserved. Full original upstream prose remains in vendor/docs and is not represented as fully translated.