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

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

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

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

Multiple queries

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

SSR with ssrWidth

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

ssrWidth is used to statically evaluate the query when window is unavailable, preventing a layout shift between the server-rendered markup and the first client render.

Type Declarations

export declare function evaluateSSRQuery(query: string, ssrWidth: number): boolean;
export interface UseMediaQueryOptions {
    ssrWidth?: number;
}
export type UseMediaQueryReturn = Observable<boolean>;
export declare function useMediaQuery(query: MaybeObservable<string>, options?: UseMediaQueryOptions): UseMediaQueryReturn;

Source

View on GitHub

Contributors

• tigerwest

Changelog

• a7392ab 2026-03-06 - feat(core,browser): add sync strategy hooks (tigerwest)