Browser

useMediaQuery

Tracks a CSS media query string as a reactive Observable<boolean>. Subscribes to MediaQueryList change events and updates automatically. SSR-safe: accepts an optional ssrWidth to statically evaluate min-width / max-width queries on the server.

Demo

isLargeScreenfalse
prefersDarkfalse

Usage

Hook
Scope

import { 
const useMediaQuery: (query: MaybeObservable<string>, options?: DeepMaybeObservable<UseMediaQueryOptions>) => UseMediaQueryReturn
useMediaQuery } from "@usels/web";

function 
function Component(): JSX.Element
Component() {
  const 
const isLarge$: any
isLarge$ = 
function useMediaQuery(query: MaybeObservable<string>, options?: DeepMaybeObservable<UseMediaQueryOptions>): UseMediaQueryReturn
Framework-agnostic reactive CSS media query tracker.
Creates a MediaQueryList for the given query (reactive — accepts
MaybeObservable<string>) and subscribes to its change events via
createEventListener. Re-creates the MediaQueryList when the query or
the resolved window changes. Must be called inside a useScope factory.
@param ― query - CSS media query (plain string or Observable<string>).
@param ― options - Optional { window?, ssrWidth? }.
@returns ― Observable<boolean> that reflects mql.matches (or the SSR
fallback when matchMedia is unavailable).
useMediaQuery("(min-width: 1024px)");

  return <
JSX.IntrinsicElements.p: DetailedHTMLProps<HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>
p>{
const isLarge$: any
isLarge$.
any
get() ? "Large screen" : "Small screen"}</
JSX.IntrinsicElements.p: DetailedHTMLProps<HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>
p>;
}

import { createMediaQuery } from "@usels/web";

function Component() {
  "use scope"
  const isLarge$ = createMediaQuery("(min-width: 1024px)");

  return <p>{isLarge$.get() ? "Large screen" : "Small screen"}</p>;
}

Multiple queries

Hook
Scope

import { useMediaQuery } from "@usels/web";

function Component() {
  const isLarge$ = useMediaQuery("(min-width: 1024px)");
  const prefersDark$ = useMediaQuery("(prefers-color-scheme: dark)");
}

import { createMediaQuery } from "@usels/web";

function Component() {
  "use scope"
  const isLarge$ = createMediaQuery("(min-width: 1024px)");
  const prefersDark$ = createMediaQuery("(prefers-color-scheme: dark)");
}

Reactive query

The query itself may be an Observable<string> — the underlying MediaQueryList is rebuilt whenever the observable changes, so the matches value always reflects the current query.

Hook
Scope

import { useObservable } from "@usels/core";
import { useMediaQuery } from "@usels/web";

function Component() {
  const query$ = useObservable("(min-width: 1024px)");
  const matches$ = useMediaQuery(query$);

  return (
    <button onClick={() => query$.set("(max-width: 480px)")}>
      {matches$.get() ? "matches" : "no match"}
    </button>
  );
}

import { observable } from "@usels/core";
import { createMediaQuery } from "@usels/web";

function Component() {
  "use scope"
  const query$ = observable("(min-width: 1024px)");
  const matches$ = createMediaQuery(query$);

  return (
    <button onClick={() => query$.set("(max-width: 480px)")}>
      {matches$.get() ? "matches" : "no match"}
    </button>
  );
}

SSR with `ssrWidth`

Pass ssrWidth to statically evaluate min-width / max-width queries when window.matchMedia is unavailable. This prevents layout shift between the server-rendered markup and the first client render.

useMediaQuery("(min-width: 1024px)", { ssrWidth: 1280 });

Type

Parameters

Parameter	Type	Description
`query`	`MaybeObservable<string>`	- CSS media query (plain string or `Observable<string>`).
`options`	`UseMediaQueryOptions` (optional)	- Optional `{ window?, ssrWidth? }`.

UseMediaQueryOptions

Option	Type	Default	Description
`ssrWidth`	`number`	`-`	Static viewport width used to evaluate `min-width` / `max-width` queries when `window.matchMedia` is unavailable (SSR).
`window`	`WindowSource`	`-`	-

Returns

ObservableBoolean<boolean>

Name	Type	Description
`toggle`	`() => void`	-
`peek`	`{ (): boolean; (): boolean; }`	-
`get`	`(trackingType?: TrackingType \| GetOptions) => boolean`	-
`onChange`	`(cb: ListenerFn<boolean>, options?: { trackingType?: TrackingType; initial?: boolean \| undefined; immediate?: boolean \| undefined; noArgs?: boolean \| undefined; } \| undefined) => () => void`	-
`set`	`{ (value: (prev: boolean) => boolean): void; (value: ObservableBoolean<boolean>): void; (value: boolean \| ImmutableObservableBase<boolean> \| ... 4 more ... \| (() => boolean \| ... 1 more ... \| Promise<...>)): void; (value: Promise<...>): void; (value: boolean): void; }`	-
`delete`	`() => void`	-

Source

View on GitHub