@btja/use-tailwind-media-query 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian T
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# use-tailwind-media-query
+
+React 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. 
+
+Multiple components on the same screen can listen to the
+same media query without duplicating listeners and wasting memory.
+
+## 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
+```
+
+## API
+
+```tsx
+import {
+  useTailwindBreakpoint,
+  useIsDesktop,
+  useIsLargeDesktop,
+  useIsMobile,
+  useIsTablet,
+  useMediaQuery,
+} from '@btja/use-tailwind-media-query'
+import type { TailwindBreakpoint } from '@btja/use-tailwind-media-query'
+```
+
+Built-in tailwind breakpoints (`TailwindBreakpoint`):
+
+| Breakpoint | Min width |
+| --- | --- |
+| `sm` | `640px` |
+| `md` | `768px` |
+| `lg` | `1024px` |
+| `xl` | `1280px` |
+| `2xl` | `1536px` |
+
+Hooks:
+
+| Hook | Returns | Purpose |
+| --- | --- | --- |
+| `useMediaQuery(query: string)` | `bool` | Subscribe to any CSS media query |
+| `useTailwindBreakpoint(tailwindBreakpoint: TailwindBreakpoint)` | `bool` | Tailwind breakpoint helper |
+| `useIsMobile()` | `bool` | `true` below `md` |
+| `useIsTablet()` | `bool` | `true` from `md` to below `lg` |
+| `useIsDesktop()` | `bool` | `true` at `lg` and above |
+| `useIsLargeDesktop()` | `bool` | `true` at `xl` and above |
+
+## Examples
+
+`useIsMobile` (`useIsTablet`, `useIsDesktop`, `useIsLargeDesktop`):
+
+```tsx
+import { useIsMobile } from '@btja/use-tailwind-media-query'
+
+export function Example() {
+  const isMobile = useIsMobile()
+
+  return isMobile ? <MobileView /> : <DesktopView />
+}
+```
+
+<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
+import { useTailwindBreakpoint } from '@btja/use-tailwind-media-query'
+
+export function SidebarLayout() {
+  const showSidebar = useTailwindBreakpoint('lg')
+
+  return showSidebar ? <DesktopLayout /> : <CompactLayout />
+}
+```
+
+`useMediaQuery`:
+
+```tsx
+import { useMediaQuery } from '@btja/use-tailwind-media-query'
+
+export function MotionPreference() {
+  const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)')
+
+  return <p>{prefersReducedMotion ? 'Reduced motion' : 'Full motion'}</p>
+}
+```
+
+
+## SEO and SSR
+
+If possible, keep both screen variants semantically equivalent. Adaptive design should
+usually change layout and density, not core content. That is safer for SEO, accessibility,
+and consistency.
+
+With this library, server render does not know the real viewport:
+
+| Hook | Server-render value |
+| --- | --- |
+| `useMediaQuery()` | `false` |
+| `useTailwindBreakpoint()` | `false` |
+| `useIsMobile()` | `true` |
+| `useIsDesktop()` | `false` |
+
+So this:
+
+```tsx
+return useIsMobile() ? <MobileView /> : <DesktopView />
+```
+
+renders the mobile branch on the server, then hydrates to the real client viewport.
+
+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.
+
+## Limitations
+Current limitation: `useMediaQuery` depends on `MediaQueryList.addEventListener` /
+`removeEventListener`. Older Safari/WebView environments that only implement
+`addListener` / `removeListener` are not supported.
+
+## Development
+Using pnpm.
+
+```bash
+pnpm install
+pnpm run play # run vite playground
+pnpm run test
+pnpm run typecheck
+pnpm run build
+```
+
+Before releasing (after `npm login`):
+
+```bash
+pnpm bump:version
+pnpm check:release
+npm publish --access public
+```

package/dist/index.cjs

@@ -0,0 +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;

package/dist/index.d.cts

@@ -0,0 +1,21 @@
+//#region src/useMediaQuery.d.ts
+declare function useMediaQuery(query: string): boolean;
+//#endregion
+//#region src/tailwindBreakpoints.d.ts
+declare const tailwindBreakpointQueries: {
+  readonly sm: "(min-width: 640px)";
+  readonly md: "(min-width: 768px)";
+  readonly lg: "(min-width: 1024px)";
+  readonly xl: "(min-width: 1280px)";
+  readonly "2xl": "(min-width: 1536px)";
+};
+type TailwindBreakpoint = keyof typeof tailwindBreakpointQueries;
+//#endregion
+//#region src/useTailwindBreakpoint.d.ts
+declare function useTailwindBreakpoint(tailwindBreakpoint: TailwindBreakpoint): boolean;
+declare function useIsMobile(): boolean;
+declare function useIsTablet(): boolean;
+declare function useIsDesktop(): boolean;
+declare function useIsLargeDesktop(): boolean;
+//#endregion
+export { type TailwindBreakpoint, type tailwindBreakpointQueries, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsTablet, useMediaQuery, useTailwindBreakpoint };

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+//#region src/useMediaQuery.d.ts
+declare function useMediaQuery(query: string): boolean;
+//#endregion
+//#region src/tailwindBreakpoints.d.ts
+declare const tailwindBreakpointQueries: {
+  readonly sm: "(min-width: 640px)";
+  readonly md: "(min-width: 768px)";
+  readonly lg: "(min-width: 1024px)";
+  readonly xl: "(min-width: 1280px)";
+  readonly "2xl": "(min-width: 1536px)";
+};
+type TailwindBreakpoint = keyof typeof tailwindBreakpointQueries;
+//#endregion
+//#region src/useTailwindBreakpoint.d.ts
+declare function useTailwindBreakpoint(tailwindBreakpoint: TailwindBreakpoint): boolean;
+declare function useIsMobile(): boolean;
+declare function useIsTablet(): boolean;
+declare function useIsDesktop(): boolean;
+declare function useIsLargeDesktop(): boolean;
+//#endregion
+export { type TailwindBreakpoint, type tailwindBreakpointQueries, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsTablet, useMediaQuery, useTailwindBreakpoint };

package/dist/index.js

@@ -0,0 +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};

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@btja/use-tailwind-media-query",
+  "type": "module",
+  "version": "0.1.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",
+  "homepage": "https://github.com/bwt2/use-tailwind-media-query#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bwt2/use-tailwind-media-query.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bwt2/use-tailwind-media-query/issues"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=14.18.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "play": "vite",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit",
+    "pack:dry-run": "npm pack --dry-run",
+    "check:release": "pnpm run build && pnpm run test -- --run && pnpm run typecheck && pnpm run pack:dry-run",
+    "bump:version": "bumpp",
+    "prepublishOnly": "pnpm run build"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/core": "^0.18.4",
+    "@rolldown/plugin-babel": "^0.2.3",
+    "@tsconfig/strictest": "^2.0.8",
+    "@types/node": "^25.6.2",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "@vitest/browser-playwright": "^4.1.5",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "bumpp": "^11.1.0",
+    "publint": "^0.3.21",
+    "tsdown": "^0.22.0",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.11",
+    "vitest": "^4.1.5",
+    "vitest-browser-react": "^2.2.0"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  }
+}