useMediaQueryuseMediaQuery

matchMedia 쿼리 하나를 추적하고, 서버와 첫 클라이언트 렌더에서는 같은 값을 씁니다.Track one matchMedia query, agreeing with the server on the first render.

사용법Usage

columns.tsx

import { type ReactNode } from "react";

import { useMediaQuery } from "@horon-ai/react";

function Columns({ children }: { children: ReactNode }) {
  const wide = useMediaQuery("(min-width: 768px)");
  return <div className={wide ? "grid grid-cols-3 gap-4" : "flex flex-col gap-3"}>{children}</div>;
}

시그니처Signature

use-media-query.ts

export function useMediaQuery(query: string, serverValue = false): boolean

매개변수Parameters

이름Name	타입Type	기본값Default	설명Description
`query`	`string`	`-`	(max-width: 767px)나 (prefers-reduced-motion: reduce) 같은 미디어 쿼리입니다.A media query such as (max-width: 767px) or (prefers-reduced-motion: reduce).
`serverValue`	`boolean`	`false`	서버 렌더와 matchMedia가 없을 때 보고할 값입니다.Result to report while rendering on the server or before matchMedia is available.

반환값Returns

쿼리가 지금 일치하는지 여부입니다. 서버와 첫 패스에서는 serverValue를 돌려줍니다.Whether the query currently matches, or serverValue on the server and in the first pass.

동작과 주의Behavior notes

서버 렌더와 첫 클라이언트 렌더가 serverValue를 쓰므로 정적 썸네일과 하이드레이션이 브라우저의 실제 상태를 읽기 전에 서로 맞습니다.The server render and the first client render use serverValue, so static thumbnails and hydration agree before the browser reports the real state.
query가 바뀌면 구독을 다시 만듭니다. 캐시 키가 문자열 자체이므로 렌더 사이에 값이 바뀌지 않는 리터럴을 넘깁니다.The subscription is rebuilt when query changes, and the cache key is the string itself, so the query must be a literal the caller keeps stable across renders.
window.matchMedia가 없으면 서버 스냅샷과 클라이언트 스냅샷 모두 serverValue로 돌아갑니다.Both the server snapshot and the snapshot taken before window.matchMedia exists fall back to serverValue.