useMediaQuery

اشتراک در یک media query و دریافت وضعیت تطبیق آن — SSR-safe

معرفی

هوک useMediaQuery به یک CSS media query گوش می‌دهد و وضعیتِ تطبیقِ فعلیِ آن را برمی‌گرداند. SSR-safe است: روی سرور و در اولین رندرِ کلاینت undefined برمی‌گرداند، پس مصرف‌کننده باید حالتِ undefined را هندل کند (تا از پرشِ ناخواسته جلوگیری شود).

چه زمانی استفاده کنیم

رفتارِ واکنش‌گرا بر اساس breakpoint که با CSS تنها ممکن نیست (مثلاً تغییرِ ساختارِ کامپوننت)
واکنش به prefers-color-scheme یا prefers-reduced-motion

چه زمانی استفاده نکنیم

برای استایلِ صرفِ واکنش‌گرا — از کلاس‌های واکنش‌گرای Tailwind (md:, lg:) استفاده کنید
برای تشخیصِ موبایل در چیدمانِ DS — هوکِ آماده‌ی useIsMobile را ببینید

استفاده

import { useMediaQuery, useBreakpoint } from '@partodata/ui'

function Layout() {
  const isLarge = useMediaQuery('(min-width: 1024px)')
  const reducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)')

  // یا با میان‌بُرِ breakpoint:
  const isDesktop = useBreakpoint('lg')

  if (isLarge === undefined) return null // هنوز hydrate نشده
  return isLarge ? <DesktopNav /> : <MobileNav />
}

API

`useMediaQuery(query)`

پارامتر	نوع	توضیح
`query`	`string`	رشته‌ی media query (مثلاً `'(min-width: 768px)'`)

بازگشتی: boolean \| undefined — تا پیش از hydration undefined است.

`useBreakpoint(breakpoint)`

میان‌بُری برای breakpointهای استانداردِ Tailwind.

پارامتر	نوع	توضیح
`breakpoint`	`'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`	نقطه‌ی شکستِ `min-width` متناظر

بازگشتی: boolean \| undefined.

هوک‌های مرتبط

تشخیصِ موبایلِ آماده‌ی DS → useIsMobile
خواندنِ توکن‌های تم در زمان اجرا → useRootStyles