MediaQueryProvider

@coinbase/cds-web@8.13.6

Manages window.matchMedia subscriptions with SSR support.

Import

import { MediaQueryProvider } from '@coinbase/cds-web/system/MediaQueryProvider'

SourceView source codeStorybookView Storybook

---

Related components

• useMediaQuery,
• useBreakpoints

MediaQueryProvider component

The MediaQueryProvider manages window.matchMedia subscriptions with SSR support.

Provides a single state shared by all subscriptions to ensure Suspense works correctly.

Use the defaultValues prop to configure SSR defaults, and the useMediaQuery hook to subscribe to window.matchMedia changes.

See the useMediaQuery docs here →

Basic usage

Use the useMediaQuery hook to call window.matchMedia with SSR support. It must be used within a MediaQueryProvider component.

This hook is ideal for conditional rendering based on viewport size, user preferences, or other media features.

It subscribes to a single state shared by all media queries to ensure Suspense works correctly.

See the useMediaQuery docs here →

󰣸

Warning

Do not use useMediaQuery for responsive styles. Use CSS media queries or the StyleProps API for responsive styles.

Loading...

󰙡

Live Code

() => {
  const Page = () => {
    const isMobile = useMediaQuery('(max-width: 767px)');
    const prefersDarkMode = useMediaQuery('(prefers-color-scheme: dark)');
    return <JSONCodeBlock json={{ isMobile, prefersDarkMode }} />;
  };

  const App = () => (
    <MediaQueryProvider defaultValues={{ width: 1200, colorScheme: 'light' }}>
      <Page />
    </MediaQueryProvider>
  );

  return <App />;
};

SSR support

The MediaQueryProvider defaultValues are used to provide consistent behavior between server and client rendering.

On the client the native window.matchMedia API is used. On the server the component solves the window.matchMedia queries by comparing to the defaultValues.

The comparison against defaultValues during SSR is limited: it cannot solve highly complex media queries. If a complex query cannot be solved during SSR the hook will simply return false, and the query can still be solved by window.matchMedia on the client.

󰔂

Tip

You can populate the defaultValues prop with user preferences, cookies, etc. to ensure the correct styles are applied on the server.

Simple queries that can be solved during SSR

• Simple media queries
• width, min-width, max-width, height, min-height, and max-height with pixel or em units
• prefers-contrast and prefers-color-scheme
• Logical and operator

Complex queries that cannot be solved during SSR

• Multiple comma-delimited values
• Logical not and or operators
• Mathematical <= and >= operators
• Complex or nested queries
• Other media types or features

Complex queries on the client

Complex queries cannot be solved during SSR. They are solved on the client by calling window.matchMedia.

Loading...

󰙡

Live Code

() => {
  const isPortrait = useMediaQuery('(orientation: portrait)');
  const isHighDPI = useMediaQuery('(min-resolution: 2dppx)');
  const isTouch = useMediaQuery('(pointer: coarse)');
  const isMediumHeight = useMediaQuery('(min-height: 600px) and (max-height: 900px)');

  const complexQuery = useMediaQuery(
    `((width >= 1200px) and (orientation: landscape)),
    (width < 560px) or ((width > 768px) and (width < 900px))`,
  );

  return <JSONCodeBlock json={{ isPortrait, isHighDPI, isTouch, isMediumHeight, complexQuery }} />;
};