@btja/use-tailwind-media-query 0.1.1 → 0.2.0

package/README.md

@@ -1,38 +1,30 @@
 # use-tailwind-media-query
 
-React hooks for Tailwind-style breakpoints and arbitrary media queries.
+React 19 hooks for Tailwind-style breakpoints and arbitrary media queries.
 
-## Motivation 
-
-### Adaptive design
-
-
-This hook is intended to be used in adaptive designs in React.
-
-Use adaptive design when layouts should change across breakpoints (for example: dashboards, dense data views, and flows on desktop vs mobile). Prefer plain responsive design when the same hierarchy still works and only spacing,
-columns, or typography need to change.
-
-### Store
-
-The hooks share a small media-query store so repeated breakpoint checks can reuse the
-same underlying subscription instead of attaching duplicate `matchMedia` listeners in
-every component. 
+<table align="center">
+  <tr>
+    <td align="center">
+      <img src="docs/desktop-view.png" alt="Desktop adaptive view" height="320" />
+      <div><strong>Desktop view</strong></div>
+    </td>
+    <td align="center">
+      <img src="docs/mobile-view.png" alt="Mobile adaptive view" height="320" />
+      <div><strong>Mobile view</strong></div>
+    </td>
+  </tr>
+</table>
 
-Multiple components on the same screen can listen to the
-same media query without duplicating listeners and wasting memory.
+<div align="center">
+  <a href="https://bwt2.github.io/use-tailwind-media-query">Live demo</a>
+</div>
 
 ## Installation
 
 ```bash
 npm i @btja/use-tailwind-media-query
-```
-```bash
 yarn add @btja/use-tailwind-media-query
-```
-```bash
 pnpm add @btja/use-tailwind-media-query
-```
-```bash
 bun add @btja/use-tailwind-media-query
 ```
 
@@ -64,8 +56,8 @@ Hooks:
 
 | Hook | Returns | Purpose |
 | --- | --- | --- |
-| `useMediaQuery(query: string)` | `bool` | Subscribe to any CSS media query |
-| `useTailwindBreakpoint(tailwindBreakpoint: TailwindBreakpoint)` | `bool` | Tailwind breakpoint helper |
+| `useMediaQuery(query: string, options?)` | `bool` | Subscribe to any CSS media query |
+| `useTailwindBreakpoint(tailwindBreakpoint: TailwindBreakpoint, options?)` | `bool` | Tailwind breakpoint helper |
 | `useIsMobile()` | `bool` | `true` below `md` |
 | `useIsTablet()` | `bool` | `true` from `md` to below `lg` |
 | `useIsDesktop()` | `bool` | `true` at `lg` and above |
@@ -85,19 +77,6 @@ export function Example() {
 }
 ```
 
-<table align="center">
-  <tr>
-    <td align="center">
-      <img src="docs/desktop-view.png" alt="Desktop adaptive view" height="320" />
-      <div><strong>Desktop view</strong></div>
-    </td>
-    <td align="center">
-      <img src="docs/mobile-view.png" alt="Mobile adaptive view" height="320" />
-      <div><strong>Mobile view</strong></div>
-    </td>
-  </tr>
-</table>
-
 `useTailwindBreakpoint`:
 
 ```tsx
@@ -110,6 +89,16 @@ export function SidebarLayout() {
 }
 ```
 
+```tsx
+import { useTailwindBreakpoint } from '@btja/use-tailwind-media-query'
+
+export function SsrSidebarLayout() {
+  const showSidebar = useTailwindBreakpoint('lg', { noWindowDefault: true })
+
+  return showSidebar ? <DesktopLayout /> : <CompactLayout />
+}
+```
+
 `useMediaQuery`:
 
 ```tsx
@@ -122,18 +111,31 @@ export function MotionPreference() {
 }
 ```
 
+```tsx
+import { useMediaQuery } from '@btja/use-tailwind-media-query'
+
+export function SsrDesktopShell() {
+  const isDesktop = useMediaQuery('(min-width: 1024px)', { noWindowDefault: true })
+
+  return isDesktop ? <DesktopShell /> : <MobileShell />
+}
+```
+
 
 ## SEO and SSR
 
 If possible, keep both screen variants semantically equivalent for SEO, accessibility,
 and consistency purposes.
 
-With this library, server render does not know the real viewport:
+With this library, server render does not know the real viewport unless you provide an
+explicit fallback with `noWindowDefault`:
 
 | Hook | Server-render value |
 | --- | --- |
 | `useMediaQuery()` | `false` |
+| `useMediaQuery(query, { noWindowDefault: true })` | `true` |
 | `useTailwindBreakpoint()` | `false` |
+| `useTailwindBreakpoint(breakpoint, { noWindowDefault: true })` | `true` |
 | `useIsMobile()` | `true` |
 | `useIsDesktop()` | `false` |
 
@@ -145,6 +147,19 @@ return useIsMobile() ? <MobileView /> : <DesktopView />
 
 renders the mobile branch on the server, then hydrates to the real client viewport.
 
+Use `noWindowDefault` when you want the server-rendered branch to default to a known
+assumption before the browser can evaluate `matchMedia`. This is useful when your SSR
+environment already has a strong hint about the likely viewport and you want to reduce
+layout flipping during hydration.
+
+Ways to choose `noWindowDefault` on the server include:
+- infer a mobile/desktop default from the user-agent string
+- use device hints or request headers provided by your framework, CDN, or edge runtime
+- store a prior device preference in a cookie and reuse it during SSR
+- pick a product-level default such as mobile-first when no reliable hint exists
+
+If the server guess is wrong, the client will correct to the real media-query result after hydration (with risk of layout flash).
+
 If SEO matters, avoid putting unique primary content in only one branch. Keep headings,
 copy, links, and other canonical content the same when possible, and reserve screen-
 specific differences for layout or secondary UI.
@@ -154,6 +169,26 @@ Current limitation: `useMediaQuery` depends on `MediaQueryList.addEventListener`
 `removeEventListener`. Older Safari/WebView environments that only implement
 `addListener` / `removeListener` are not supported.
 
+
+## Motivation 
+
+### Adaptive design
+
+
+This hook is intended to be used in adaptive designs in React.
+
+Use adaptive design when layouts should change across breakpoints (for example: dashboards, dense data views, and flows on desktop vs mobile). Prefer plain responsive design when the same hierarchy still works and only spacing,
+columns, or typography need to change.
+
+### Store
+
+The hooks share a small media-query store so repeated breakpoint checks can reuse the
+same underlying subscription instead of attaching duplicate `matchMedia` listeners in
+every component. 
+
+Multiple components on the same screen can listen to the
+same media query without duplicating listeners and wasting memory.
+
 ## Development
 Using pnpm.
 
@@ -174,14 +209,14 @@ pnpm run build
 Before releasing (after `npm login`):
 
 ```bash
-pnpm bump:version
 pnpm check:release
+pnpm bump:version
+
 npm publish --access public
 ```
 
 ## AI Disclosure
-Codex 5.4 was used to review and sanity-check:
-- tsdown configs using the official [tsdown agent skill](https://tsdown.dev/guide/skills).
-- React hook implementation for any issues.
-
-Codex 5.4 was used to generate mockup UI in '`./playground`' demo.
+Codex 5.4 was used to review and sanity-check the code. Codex was also used for:
+- Mockup UI in '`./playground`' demo
+- JSDoc
+- Tests

package/dist/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("react/compiler-runtime"),t=require("react");const n=new Map;function r(e){let t=typeof window<`u`?window.matchMedia(e):void 0,r=new Set,i=()=>{r.forEach(e=>e())};return{getSnapshot(){return(t==null?void 0:t.matches)??!1},getServerSnapshot(){return!1},subscribe(a){return t?(r.add(a),r.size===1&&t.addEventListener(`change`,i),()=>{r.delete(a),r.size===0&&(t.removeEventListener(`change`,i),n.delete(e))}):()=>{}}}}function i(e){let t=n.get(e);return t||(t=r(e),n.set(e,t)),t}function a(n){let r=(0,e.c)(2),a;r[0]===n?a=r[1]:(a=i(n),r[0]=n,r[1]=a);let o=a;return(0,t.useSyncExternalStore)(o.subscribe,o.getSnapshot,o.getServerSnapshot)}const o={sm:`(min-width: 640px)`,md:`(min-width: 768px)`,lg:`(min-width: 1024px)`,xl:`(min-width: 1280px)`,"2xl":`(min-width: 1536px)`};function s(e){return a(o[e])}function c(){return!s(`md`)}function l(){let e=s(`md`),t=s(`lg`);return e&&!t}function u(){return s(`lg`)}function d(){return s(`xl`)}exports.useIsDesktop=u,exports.useIsLargeDesktop=d,exports.useIsMobile=c,exports.useIsTablet=l,exports.useMediaQuery=a,exports.useTailwindBreakpoint=s;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("react/compiler-runtime"),t=require("react");const n=new Map;function r(e,t=!1,r=e){let i=typeof window<`u`?window.matchMedia(e):void 0,a=new Set,o=()=>{a.forEach(e=>e())};return{getSnapshot(){return(i==null?void 0:i.matches)??t},getServerSnapshot(){return t},subscribe(e){return i?(a.add(e),a.size===1&&i.addEventListener(`change`,o),()=>{a.delete(e),a.size===0&&(i.removeEventListener(`change`,o),n.delete(r))}):()=>{}}}}function i(e,t=!1){if(typeof window>`u`)return r(e,t);let i=`${e}::${String(t)}`,a=n.get(i);return a||(a=r(e,t,i),n.set(i,a)),a}function a(n,r){let a=(0,e.c)(5),o;a[0]===r?o=a[1]:(o=r===void 0?{}:r,a[0]=r,a[1]=o);let s=o.noWindowDefault??!1,c;a[2]!==n||a[3]!==s?(c=i(n,s),a[2]=n,a[3]=s,a[4]=c):c=a[4];let l=c;return(0,t.useSyncExternalStore)(l.subscribe,l.getSnapshot,l.getServerSnapshot)}const o={sm:`(min-width: 640px)`,md:`(min-width: 768px)`,lg:`(min-width: 1024px)`,xl:`(min-width: 1280px)`,"2xl":`(min-width: 1536px)`};function s(e,t){return a(o[e],t)}function c(){return!s(`md`)}function l(){let e=s(`md`),t=s(`lg`);return e&&!t}function u(){return s(`lg`)}function d(){return s(`xl`)}exports.useIsDesktop=u,exports.useIsLargeDesktop=d,exports.useIsMobile=c,exports.useIsTablet=l,exports.useMediaQuery=a,exports.useTailwindBreakpoint=s;

package/dist/index.d.cts

@@ -1,7 +1,19 @@
 //#region src/useMediaQuery.d.ts
-declare function useMediaQuery(query: string): boolean;
+type UseMediaQueryOptions = {
+  /**
+  * Value returned when `window` is unavailable, such as during server rendering.
+  */
+  noWindowDefault?: boolean;
+};
+/**
+* Subscribes to an arbitrary CSS media query and returns whether it currently matches.
+*/
+declare function useMediaQuery(query: string, options?: UseMediaQueryOptions): boolean;
 //#endregion
 //#region src/tailwindBreakpoints.d.ts
+/**
+* Built-in Tailwind-style media queries keyed by breakpoint name.
+*/
 declare const tailwindBreakpointQueries: {
   readonly sm: "(min-width: 640px)";
   readonly md: "(min-width: 768px)";
@@ -9,13 +21,31 @@ declare const tailwindBreakpointQueries: {
   readonly xl: "(min-width: 1280px)";
   readonly "2xl": "(min-width: 1536px)";
 };
+/**
+* Supported Tailwind breakpoint names for the built-in breakpoint helpers.
+*/
 type TailwindBreakpoint = keyof typeof tailwindBreakpointQueries;
 //#endregion
 //#region src/useTailwindBreakpoint.d.ts
-declare function useTailwindBreakpoint(tailwindBreakpoint: TailwindBreakpoint): boolean;
+/**
+* Subscribes to one of the built-in Tailwind breakpoint queries.
+*/
+declare function useTailwindBreakpoint(tailwindBreakpoint: TailwindBreakpoint, options?: UseMediaQueryOptions): boolean;
+/**
+* Returns `true` when the viewport is smaller than Tailwind's `md` breakpoint.
+*/
 declare function useIsMobile(): boolean;
+/**
+* Returns `true` when the viewport is between Tailwind's `md` and `lg` breakpoints.
+*/
 declare function useIsTablet(): boolean;
+/**
+* Returns `true` when the viewport is at or above Tailwind's `lg` breakpoint.
+*/
 declare function useIsDesktop(): boolean;
+/**
+* Returns `true` when the viewport is at or above Tailwind's `xl` breakpoint.
+*/
 declare function useIsLargeDesktop(): boolean;
 //#endregion
-export { type TailwindBreakpoint, type tailwindBreakpointQueries, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsTablet, useMediaQuery, useTailwindBreakpoint };
+export { type TailwindBreakpoint, UseMediaQueryOptions, type tailwindBreakpointQueries, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsTablet, useMediaQuery, useTailwindBreakpoint };

package/dist/index.d.ts

@@ -1,7 +1,19 @@
 //#region src/useMediaQuery.d.ts
-declare function useMediaQuery(query: string): boolean;
+type UseMediaQueryOptions = {
+  /**
+  * Value returned when `window` is unavailable, such as during server rendering.
+  */
+  noWindowDefault?: boolean;
+};
+/**
+* Subscribes to an arbitrary CSS media query and returns whether it currently matches.
+*/
+declare function useMediaQuery(query: string, options?: UseMediaQueryOptions): boolean;
 //#endregion
 //#region src/tailwindBreakpoints.d.ts
+/**
+* Built-in Tailwind-style media queries keyed by breakpoint name.
+*/
 declare const tailwindBreakpointQueries: {
   readonly sm: "(min-width: 640px)";
   readonly md: "(min-width: 768px)";
@@ -9,13 +21,31 @@ declare const tailwindBreakpointQueries: {
   readonly xl: "(min-width: 1280px)";
   readonly "2xl": "(min-width: 1536px)";
 };
+/**
+* Supported Tailwind breakpoint names for the built-in breakpoint helpers.
+*/
 type TailwindBreakpoint = keyof typeof tailwindBreakpointQueries;
 //#endregion
 //#region src/useTailwindBreakpoint.d.ts
-declare function useTailwindBreakpoint(tailwindBreakpoint: TailwindBreakpoint): boolean;
+/**
+* Subscribes to one of the built-in Tailwind breakpoint queries.
+*/
+declare function useTailwindBreakpoint(tailwindBreakpoint: TailwindBreakpoint, options?: UseMediaQueryOptions): boolean;
+/**
+* Returns `true` when the viewport is smaller than Tailwind's `md` breakpoint.
+*/
 declare function useIsMobile(): boolean;
+/**
+* Returns `true` when the viewport is between Tailwind's `md` and `lg` breakpoints.
+*/
 declare function useIsTablet(): boolean;
+/**
+* Returns `true` when the viewport is at or above Tailwind's `lg` breakpoint.
+*/
 declare function useIsDesktop(): boolean;
+/**
+* Returns `true` when the viewport is at or above Tailwind's `xl` breakpoint.
+*/
 declare function useIsLargeDesktop(): boolean;
 //#endregion
-export { type TailwindBreakpoint, type tailwindBreakpointQueries, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsTablet, useMediaQuery, useTailwindBreakpoint };
+export { type TailwindBreakpoint, UseMediaQueryOptions, type tailwindBreakpointQueries, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsTablet, useMediaQuery, useTailwindBreakpoint };

package/dist/index.js

@@ -1 +1 @@
-import{c as e}from"react/compiler-runtime";import{useSyncExternalStore as t}from"react";const n=new Map;function r(e){let t=typeof window<`u`?window.matchMedia(e):void 0,r=new Set,i=()=>{r.forEach(e=>e())};return{getSnapshot(){return(t==null?void 0:t.matches)??!1},getServerSnapshot(){return!1},subscribe(a){return t?(r.add(a),r.size===1&&t.addEventListener(`change`,i),()=>{r.delete(a),r.size===0&&(t.removeEventListener(`change`,i),n.delete(e))}):()=>{}}}}function i(e){let t=n.get(e);return t||(t=r(e),n.set(e,t)),t}function a(n){let r=e(2),a;r[0]===n?a=r[1]:(a=i(n),r[0]=n,r[1]=a);let o=a;return t(o.subscribe,o.getSnapshot,o.getServerSnapshot)}const o={sm:`(min-width: 640px)`,md:`(min-width: 768px)`,lg:`(min-width: 1024px)`,xl:`(min-width: 1280px)`,"2xl":`(min-width: 1536px)`};function s(e){return a(o[e])}function c(){return!s(`md`)}function l(){let e=s(`md`),t=s(`lg`);return e&&!t}function u(){return s(`lg`)}function d(){return s(`xl`)}export{u as useIsDesktop,d as useIsLargeDesktop,c as useIsMobile,l as useIsTablet,a as useMediaQuery,s as useTailwindBreakpoint};
+import{c as e}from"react/compiler-runtime";import{useSyncExternalStore as t}from"react";const n=new Map;function r(e,t=!1,r=e){let i=typeof window<`u`?window.matchMedia(e):void 0,a=new Set,o=()=>{a.forEach(e=>e())};return{getSnapshot(){return(i==null?void 0:i.matches)??t},getServerSnapshot(){return t},subscribe(e){return i?(a.add(e),a.size===1&&i.addEventListener(`change`,o),()=>{a.delete(e),a.size===0&&(i.removeEventListener(`change`,o),n.delete(r))}):()=>{}}}}function i(e,t=!1){if(typeof window>`u`)return r(e,t);let i=`${e}::${String(t)}`,a=n.get(i);return a||(a=r(e,t,i),n.set(i,a)),a}function a(n,r){let a=e(5),o;a[0]===r?o=a[1]:(o=r===void 0?{}:r,a[0]=r,a[1]=o);let s=o.noWindowDefault??!1,c;a[2]!==n||a[3]!==s?(c=i(n,s),a[2]=n,a[3]=s,a[4]=c):c=a[4];let l=c;return t(l.subscribe,l.getSnapshot,l.getServerSnapshot)}const o={sm:`(min-width: 640px)`,md:`(min-width: 768px)`,lg:`(min-width: 1024px)`,xl:`(min-width: 1280px)`,"2xl":`(min-width: 1536px)`};function s(e,t){return a(o[e],t)}function c(){return!s(`md`)}function l(){let e=s(`md`),t=s(`lg`);return e&&!t}function u(){return s(`lg`)}function d(){return s(`xl`)}export{u as useIsDesktop,d as useIsLargeDesktop,c as useIsMobile,l as useIsTablet,a as useMediaQuery,s as useTailwindBreakpoint};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@btja/use-tailwind-media-query",
   "type": "module",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Helper react hook to listen for tailwind media breakpoints. Intended for use with adaptive design.",
   "author": "Brian W Tjahjadi <brian.w.tjahjadi@gmail.com>",
   "license": "MIT",
@@ -13,7 +13,10 @@
     "react-hooks",
     "hook",
     "custom-hook",
-    "use-tailwind-media-query"
+    "use-tailwind-media-query",
+    "tailwind-media-query",
+    "tailwind-breakpoints",
+    "adaptive-design"
   ],
   "homepage": "https://github.com/bwt2/use-tailwind-media-query#readme",
   "repository": {
@@ -37,6 +40,7 @@
     "build": "tsdown",
     "dev": "tsdown --watch",
     "play": "vite",
+    "play:build": "vite build",
     "test": "vitest",
     "typecheck": "tsc --noEmit",
     "pack:dry-run": "npm pack --dry-run",