{"_id":"vue-viewports","_rev":"29-c9f7e5bdd30a5c63f1c922ff7370e382","name":"vue-viewports","dist-tags":{"latest":"4.1.0"},"versions":{"0.1.0":{"name":"vue-viewports","version":"0.1.0","author":{"name":"Marco Boffo","email":"=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/vue-viewports.js","require":"./dist/vue-viewports.cjs"},"./package.json":"./package.json"},"gitHead":"dd99ba7f99ef30c5141c2749219ed517ce9227a7","scripts":{"dev":"vite","lint":"eslint .","test":"vitest run","build":"vite build","coverage":"vitest run --coverage","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:564bf33a-9d0a-44fd-82e1-6ee0cf3c8391"}},"repository":{"url":"git+https://github.com/scaccogatto/vue-viewports.git","type":"git"},"_npmVersion":"11.17.0","description":"Named, reactive, matchMedia-based viewport breakpoints for Vue 3 — a tiny plugin and composable.","directories":{},"sideEffects":false,"_nodeVersion":"24.17.0","_hasShrinkwrap":false,"devDependencies":{"vue":"^3.5.39","vite":"^8.1.0","jsdom":"^29.1.1","eslint":"^10.6.0","vitest":"^4.1.9","@eslint/js":"^10.0.1","typescript":"^6.0.3","@vue/test-utils":"^2.4.11","vite-plugin-dts":"^5.0.3","typescript-eslint":"^8.62.0","@vitest/coverage-v8":"^4.1.9"},"peerDependencies":{"vue":"^3.3.0"},"_npmOperationalInternal":{"tmp":"tmp/vue-viewports_4.0.0_1782646585357_0.8230769925847821","host":"s3://npm-registry-packages-npm-production"}},"4.0.1":{"name":"vue-viewports","version":"4.0.1","keywords":["vue","vue3","viewport","viewports","responsive","breakpoints","media-query","matchmedia","composable","plugin","composition-api","typescript","vite"],"author":{"name":"Marco Boffo","email":"marcoboffo.waves@gmail.com"},"license":"MIT","_id":"vue-viewports@4.0.1","maintainers":[{"name":"marco-gatto-boffo","email":"marcoboffo.waves@gmail.com"}],"homepage":"https://github.com/scaccogatto/vue-viewports#readme","bugs":{"url":"https://github.com/scaccogatto/vue-viewports/issues"},"dist":{"shasum":"038714af658816888ede0095e1f0b752481fb13f","tarball":"https://registry.npmjs.org/vue-viewports/-/vue-viewports-4.0.1.tgz","fileCount":10,"integrity":"sha512-+sV7VyU73pIgfRAP3ObNjmOTqtKpm3pou/ykzHgOx2h6wL2uLgTC5m1CGs4di4mD/RsYlr7jZbPy6A7ZKJOIYA==","signatures":[{"sig":"MEUCIQDs809yAgzeP2xJlKRUOHjeMvETORGBSww81JLIK+SkdwIgPct4mlxBEcyqxzeEyYjRVA1RpYuo3yi0+/CWUSwweFc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/vue-viewports@4.0.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":15474},"main":"./dist/vue-viewports.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/vue-viewports.js","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/vue-viewports.js","require":"./dist/vue-viewports.cjs"},"./package.json":"./package.json"},"gitHead":"8f5e99733dd13a1cca14c3c4ac3a8fbec95a2cb5","scripts":{"dev":"vite","lint":"eslint .","test":"vitest run","build":"vite build","coverage":"vitest run --coverage","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:564bf33a-9d0a-44fd-82e1-6ee0cf3c8391"}},"repository":{"url":"git+https://github.com/scaccogatto/vue-viewports.git","type":"git"},"_npmVersion":"11.17.0","description":"Named, reactive, matchMedia-based viewport breakpoints for Vue 3 — a tiny plugin and composable.","directories":{},"sideEffects":false,"_nodeVersion":"24.17.0","_hasShrinkwrap":false,"devDependencies":{"vue":"^3.5.39","vite":"^8.1.0","jsdom":"^29.1.1","eslint":"^10.6.0","vitest":"^4.1.9","@eslint/js":"^10.0.1","typescript":"^6.0.3","@vue/test-utils":"^2.4.11","vite-plugin-dts":"^5.0.3","typescript-eslint":"^8.62.0","@vitest/coverage-v8":"^4.1.9"},"peerDependencies":{"vue":"^3.3.0"},"_npmOperationalInternal":{"tmp":"tmp/vue-viewports_4.0.1_1782648182413_0.9290479165625944","host":"s3://npm-registry-packages-npm-production"}},"4.1.0":{"name":"vue-viewports","version":"4.1.0","description":"Named, reactive, matchMedia-based viewport breakpoints for Vue 3 — a tiny plugin and composable.","type":"module","author":{"name":"Marco Boffo","email":"marcoboffo.waves@gmail.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/scaccogatto/vue-viewports.git"},"homepage":"https://github.com/scaccogatto/vue-viewports#readme","bugs":{"url":"https://github.com/scaccogatto/vue-viewports/issues"},"keywords":["vue","vue3","viewport","viewports","responsive","breakpoints","media-query","matchmedia","composable","plugin","composition-api","typescript","vite"],"sideEffects":false,"main":"./dist/vue-viewports.cjs","module":"./dist/vue-viewports.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/vue-viewports.js","require":"./dist/vue-viewports.cjs"},"./package.json":"./package.json"},"scripts":{"dev":"vite","build":"vite build","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest","coverage":"vitest run --coverage","lint":"eslint .","prepublishOnly":"npm run typecheck && npm run test && npm run build"},"peerDependencies":{"vue":"^3.3.0"},"devDependencies":{"@eslint/js":"^10.0.1","@vitest/coverage-v8":"^4.1.9","@vue/test-utils":"^2.4.11","eslint":"^10.6.0","jsdom":"^29.1.1","typescript":"^6.0.3","typescript-eslint":"^8.62.0","vite":"^8.1.0","vite-plugin-dts":"^5.0.3","vitest":"^4.1.9","vue":"^3.5.39"},"engines":{"node":">=20"},"gitHead":"3c949833b329ed35d0842f10cd6889bc91859278","_id":"vue-viewports@4.1.0","_nodeVersion":"24.18.0","_npmVersion":"12.0.1","dist":{"integrity":"sha512-8Y3w5TsULd8nshtd6RwU//+vPcnJfBxEpaDCzDzVJgYyAvklUXGD++ZP/ulhp4GiOcKhrE4XtC6h9B0scnN96Q==","shasum":"8980dc0dc996133d9cdf24291861350353e4e8f9","tarball":"https://registry.npmjs.org/vue-viewports/-/vue-viewports-4.1.0.tgz","fileCount":10,"unpackedSize":21715,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/vue-viewports@4.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDbWVvwg+MIY9XkTOm9ztKdM6M3vhjztIsSK80XS0P6VgIgGiEX03t8jhiy/+Hkd6lvboQvfydOYFlEUhuNby4mb2c="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:564bf33a-9d0a-44fd-82e1-6ee0cf3c8391"}},"directories":{},"maintainers":[{"name":"marco-gatto-boffo","email":"marcoboffo.waves@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/vue-viewports_4.1.0_1784292880764_0.7723460075842543"},"_hasShrinkwrap":false}},"time":{"created":"2016-11-23T15:38:20.119Z","modified":"2026-07-17T12:54:41.240Z","0.1.0":"2016-11-23T15:38:20.119Z","0.1.2":"2016-11-23T15:58:44.215Z","0.1.3":"2016-11-23T16:39:32.781Z","0.1.4":"2016-11-23T16:45:15.738Z","0.1.5":"2016-11-23T16:46:32.822Z","0.1.6":"2016-11-23T16:50:50.085Z","0.2.0":"2016-11-24T11:50:23.800Z","1.0.0":"2016-11-24T11:57:54.551Z","1.0.1":"2016-11-24T12:04:44.954Z","1.1.0":"2016-11-24T13:03:07.583Z","1.1.1":"2016-11-25T12:16:15.396Z","1.1.2":"2016-12-06T15:06:42.050Z","1.1.3":"2016-12-19T11:47:49.296Z","2.0.0":"2016-12-22T07:57:27.350Z","2.0.1":"2016-12-22T08:09:05.701Z","2.1.2":"2017-01-19T14:58:26.898Z","2.1.3":"2017-01-19T14:59:47.760Z","2.2.0":"2017-02-02T13:17:31.987Z","3.0.0":"2017-11-10T12:01:54.464Z","3.0.1":"2017-11-10T12:13:27.255Z","3.0.2":"2017-11-30T11:09:44.086Z","3.1.2":"2018-03-09T09:51:50.878Z","4.0.0":"2026-06-28T11:36:25.502Z","4.0.1":"2026-06-28T12:03:02.532Z","4.1.0":"2026-07-17T12:54:40.933Z"},"bugs":{"url":"https://github.com/scaccogatto/vue-viewports/issues"},"author":{"name":"Marco Boffo","email":"marcoboffo.waves@gmail.com"},"license":"MIT","homepage":"https://github.com/scaccogatto/vue-viewports#readme","keywords":["vue","vue3","viewport","viewports","responsive","breakpoints","media-query","matchmedia","composable","plugin","composition-api","typescript","vite"],"repository":{"type":"git","url":"git+https://github.com/scaccogatto/vue-viewports.git"},"description":"Named, reactive, matchMedia-based viewport breakpoints for Vue 3 — a tiny plugin and composable.","maintainers":[{"name":"marco-gatto-boffo","email":"marcoboffo.waves@gmail.com"}],"readme":"# vue-viewports\n\n> Named, reactive, `matchMedia`-based viewport breakpoints for Vue 3 — a tiny plugin **and** composable.\n\n[![npm version](https://img.shields.io/npm/v/vue-viewports.svg)](https://www.npmjs.com/package/vue-viewports)\n[![npm downloads](https://img.shields.io/npm/dm/vue-viewports)](https://www.npmjs.com/package/vue-viewports)\n[![CI](https://github.com/scaccogatto/vue-viewports/actions/workflows/ci.yml/badge.svg)](https://github.com/scaccogatto/vue-viewports/actions/workflows/ci.yml)\n[![minzipped size](https://img.shields.io/bundlephobia/minzip/vue-viewports)](https://bundlephobia.com/package/vue-viewports)\n[![license](https://img.shields.io/npm/l/vue-viewports.svg)](./LICENSE)\n\nDefine your breakpoints once, get the **current viewport** reactively in every component. No resize listeners, no debouncing — it is backed by the browser's [`matchMedia`](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia) and updates only when a breakpoint is actually crossed.\n\n- **Reactive everywhere** — the current viewport is a shared `ref`; templates, `computed`, and `watch` all update automatically.\n- **Two APIs** — a Vue plugin (`$currentViewport` on every component) and a `useViewport()` composable.\n- **Flexible breakpoints** — a `rule` can be a `min-width` length, a `{ min, max, orientation }` range, or a raw media-query string.\n- **`useMediaQuery()`** — a standalone, SSR-safe reactive wrapper around any `matchMedia` query, for one-off responsive logic outside the named breakpoints.\n- **Typed** — ships first-class TypeScript types and a single bundled `.d.ts`.\n- **Tiny & zero-dependency** — < 1 kB gzipped, `vue` is the only (peer) dependency.\n- **ESM + CJS** — works with Vite and bundlers.\n\n## Installation\n\n```shell\nnpm install vue-viewports\n```\n\nRequires **Vue 3.3+**.\n\n## Usage\n\n### Composable (`\n\n\n```\n\n`useViewport()` returns a `readonly` ref. It lazily initializes the [default breakpoints](#default-breakpoints) on first use, so it works without the plugin. The value is `undefined` while no breakpoint matches (e.g. a width below the smallest `rule`).\n\n### Plugin\n\nInstall the plugin to expose `$currentViewport` on every component and to register your own breakpoints app-wide.\n\n```ts\nimport { createApp } from 'vue'\nimport VueViewports from 'vue-viewports'\nimport App from './App.vue'\n\ncreateApp(App)\n .use(VueViewports) // default breakpoints\n .mount('#app')\n```\n\nWith custom breakpoints:\n\n```ts\ncreateApp(App)\n .use(VueViewports, [\n { rule: '600px', label: 'small' },\n { rule: '900px', label: 'medium' },\n { rule: '1200px', label: 'large' },\n ])\n .mount('#app')\n```\n\nThen, in any component:\n\n```vue\n\n```\n\nThe plugin is **authoritative**: installing it (re)configures the shared state, overriding any defaults a composable may have lazily set up.\n\n### Custom breakpoints with the composable\n\nYou can also configure breakpoints without the plugin by calling `setupViewports` once (e.g. in your entry file):\n\n```ts\nimport { setupViewports } from 'vue-viewports'\n\nsetupViewports([{ rule: '600px', label: 'small' }, { rule: '1200px', label: 'large' }])\n```\n\n### Breakpoint rule forms\n\nA `rule` accepts any of three forms:\n\n```ts\nsetupViewports([\n { rule: '768px', label: 'tablet' }, // legacy: min-width length (unchanged)\n { rule: { min: 768, max: 1279 }, label: 'tablet-only' }, // range: min/max (px) and/or orientation\n { rule: { orientation: 'landscape' }, label: 'landscape' },\n { rule: '(prefers-color-scheme: dark)', label: 'dark-mode' }, // raw media query, used verbatim\n])\n```\n\nAll three compile to a plain media-query string internally and are matched the same way. When several rules match at once, the one with the largest numeric width (from the legacy form or a range's `min`) wins — exactly as before for all-numeric configs; a rule with no numeric width (raw query, or a range with only `max`/`orientation`) is only picked when it's the sole match.\n\n### `useMediaQuery`\n\nReactive access to any raw `matchMedia` query, independent of the named-breakpoint system above:\n\n```vue\n\n\n\n```\n\n`query` may also be a `Ref`; changing its value unsubscribes from the old query and subscribes to the new one. `useMediaQuery` is SSR-safe (`false` on the server) and, when called inside a component `setup()` or an `effectScope()`, removes its `matchMedia` listener automatically on scope disposal. Called outside any scope, it still works, but nothing disposes the listener for you.\n\n## API\n\n| Export | Description |\n| --- | --- |\n| `default` / `VueViewports` | Vue 3 plugin. `app.use(VueViewports, viewports?)`. |\n| `useViewport()` | Composable returning `Readonly>`. |\n| `useMediaQuery(query)` | Composable returning `Readonly>` for any raw `matchMedia` query; `query` may be a `string` or `Ref`. |\n| `setupViewports(viewports?)` | Imperatively (re)configure breakpoints; returns a teardown function. Idempotent. |\n| `defaultViewports` | The built-in breakpoints. |\n| `toMediaQuery(rule)` | Compiles a `ViewportRule` to a media-query string, e.g. `'768px'` → `'(min-width: 768px)'`. |\n| `computeMatch(viewports)` | Pure-ish helper: the largest currently matching viewport. |\n| `viewportInjectionKey` | `InjectionKey` for the readonly ref provided by the plugin. |\n| `$currentViewport` | Component property added by the plugin: `ViewportMatch \\| undefined`. |\n\n### Types\n\n```ts\ntype ViewportOrientation = 'portrait' | 'landscape'\n\ninterface ViewportRangeRule {\n readonly min?: number // px\n readonly max?: number // px\n readonly orientation?: ViewportOrientation\n}\n\n// legacy min-width length ('768px'), a raw media-query string (contains '('),\n// or a range object\ntype ViewportRule = string | ViewportRangeRule\n\ninterface ViewportConfig {\n readonly rule: ViewportRule\n readonly label: string // your name for the viewport, e.g. 'tablet'\n}\ntype ViewportMatch = ViewportConfig\ntype ViewportConfigList = readonly ViewportConfig[]\n```\n\nFor the legacy string form, `rule` is the width at which the viewport **starts** (inclusive); the matching viewport is the largest one whose `min-width` (or range `min`) is satisfied — see [Breakpoint rule forms](#breakpoint-rule-forms) for how ties resolve across mixed forms.\n\n### Default breakpoints\n\n| label | starts at (`min-width`) |\n| --- | --- |\n| `mobile` | `320px` |\n| `tablet` | `768px` |\n| `desktop` | `1024px` |\n| `hd-desktop` | `1920px` |\n| `qhd-desktop` | `2560px` |\n| `uhd-desktop` | `3840px` |\n\n## Migrating from v3 (Vue 2)\n\n`v4` is a full Vue 3 + TypeScript rewrite. The old `v3.x` line (Vue 2) remains installable for legacy projects: `npm install vue-viewports@3`.\n\n| v3.x (Vue 2) | v4 (Vue 3) |\n| --- | --- |\n| `Vue.use(VueViewports, options)` | `createApp(App).use(VueViewports, options)` |\n| `this.$currentViewport` | `this.$currentViewport` (unchanged) or `useViewport()` |\n| Object getters `{ rule, label }` | Plain reactive `{ rule, label }` object |\n| Not reactive ([#6](https://github.com/scaccogatto/vue-viewports/issues/6)) | Fully reactive (`ref`-backed) |\n| Bundled a `matchMedia` polyfill | Uses the native `matchMedia` API |\n\nThe `options` shape (`[{ rule, label }]`) is unchanged, so most apps only need to swap `Vue.use` for `createApp(...).use`.\n\n## License\n\n[MIT](./LICENSE) © Marco Boffo\n","readmeFilename":"README.md"}