UnflowUI
ComponentsHooks

useMediaQuery

Whether a CSS media query matches, updated live. Used by Modal to show its side panel placement as a bottom sheet on small screens.

Overview

useMediaQuery returns whether a media query currently matches and re-renders when that changes. Use it when behaviour, not only styling, depends on the viewport or a user preference. For styling alone, prefer Tailwind's responsive and motion-reduce: variants.

It is used by Modal: below 768px, placement="sidepanel" renders as a bottom sheet.

Import

import { useMediaQuery } from '@unflowio/ui/hooks/useMediaQuery';

Parameters

ParamTypeDescription
querystringRequired. A media query, as passed to window.matchMedia

Return value

TypeDescription
booleantrue while the query matches. false on the server and during hydration

Usage

import { useMediaQuery } from '@unflowio/ui/hooks/useMediaQuery';

function FilterControls() {
  const isSmall = useMediaQuery('(max-width: 639px)');

  return isSmall ? <FilterSheet /> : <FilterSidebar />;
}

Respecting a user preference:

const reduceMotion = useMediaQuery('(prefers-reduced-motion: reduce)');

Implementation notes

Server rendering. The hook returns false on the server and while hydrating, so the first client render matches the server HTML. It re-renders with the real match right after, so a matching query briefly shows the false branch on first load.

Live updates. The hook listens for the query's change event and re-subscribes when query changes.

Accessibility

Use preference queries such as prefers-reduced-motion and prefers-contrast to adapt behaviour (for example turning off animated scrolling), not only styles.