{"id":12568,"library":"vue-screen","title":"Reactive Screen Size and Media Queries for Vue 3","description":"VueScreen is a JavaScript library for Vue 3 that provides reactive access to window dimensions, media query states, and device orientation. It enables developers to easily integrate dynamic screen size information and breakpoint detection into their Vue applications. The current stable version is 2.4.2, and the project demonstrates an active release cadence with regular minor and patch updates, indicating ongoing maintenance and feature development. Key differentiators include its debounced reactive screen size updates, comprehensive media query state tracking, touch screen detection, and out-of-the-box support for popular UI framework breakpoints like Tailwind, Bootstrap, Bulma, Foundation, Materialize, and Semantic UI. It is also designed to be compatible with Server-Side Rendering (SSR) environments. Version 2.x of `vue-screen` specifically targets Vue 3 applications, with previous versions (v1.x) supporting Vue 2.","status":"active","version":"2.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/reegodev/vue-screen","tags":["javascript","vuejs","vue","screen","size","window","reactive window","media query","matchMedia","typescript"],"install":[{"cmd":"npm install vue-screen","lang":"bash","label":"npm"},{"cmd":"yarn add vue-screen","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-screen","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for Vue 3.x applications.","package":"vue","optional":false}],"imports":[{"note":"This is a Composition API hook. VueScreen v2 is ESM-first and requires Vue 3.","wrong":"const useScreen = require('vue-screen').useScreen","symbol":"useScreen","correct":"import { useScreen } from 'vue-screen'"},{"note":"A Composition API hook used for accessing UI framework grid breakpoints. Takes an optional framework name (e.g., 'bulma').","wrong":"import useGrid from 'vue-screen'","symbol":"useGrid","correct":"import { useGrid } from 'vue-screen'"},{"note":"This is the default export for the plugin installation, typically used with the Options API.","wrong":"import { VueScreen } from 'vue-screen'","symbol":"VueScreen","correct":"import VueScreen from 'vue-screen'"}],"quickstart":{"code":"import { createApp } from 'vue'\nimport { useScreen, useGrid } from 'vue-screen'\nimport VueScreen from 'vue-screen'\n\nconst App = {\n  setup() {\n    const screen = useScreen();\n    const grid = useGrid('tailwind'); // Or 'bootstrap', 'bulma', etc.\n\n    return {\n      screen,\n      grid\n    };\n  },\n  template: `\n    <div>\n      <h1>VueScreen Demo</h1>\n      <p>Window Width: {{ screen.width }}px</p>\n      <p>Window Height: {{ screen.height }}px</p>\n      <p>Current Breakpoint: {{ grid.breakpoint }}</p>\n      <p>Is Mobile: {{ grid.isMobile }}</p>\n      <p>Is Desktop: {{ grid.isDesktop }}</p>\n      <p>Orientation: {{ screen.orientation }}</p>\n    </div>\n  `\n};\n\n// Option 1: Using Composition API directly in a component (as shown above)\n// Note: For global access or Options API, use as a plugin:\nconst app = createApp(App);\napp.use(VueScreen, 'bootstrap'); // Installs as a plugin with Bootstrap breakpoints\napp.mount('#app');\n\n// You can inspect the global properties with Options API in a child component:\n// <template>\n//   <ul>\n//     <li>Current breakpoint is: {{ $grid.breakpoint }}</li>\n//     <li>Window width is: {{ $screen.width }}</li>\n//   </ul>\n// </template>\n","lang":"typescript","description":"Demonstrates how to use `vue-screen` with the Composition API to access reactive screen dimensions and grid breakpoints, and how to install it as a global plugin."},"warnings":[{"fix":"For Vue 2 projects, install `vue-screen@1`. For Vue 3 projects, ensure your `vue` peer dependency is `^3.0.0` and that you are using the v2 API.","message":"Version 2.x of `vue-screen` is exclusively compatible with Vue 3. Applications using Vue 2 must remain on `vue-screen` v1.x or upgrade their Vue project to Vue 3.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Refer to the official upgrading guide in the documentation (https://reegodev.github.io/vue-screen/guide/upgrading) for detailed migration steps.","message":"Upgrading from `vue-screen` v1 to v2 introduces significant API and configuration changes. The primary API shifted towards Composition API hooks (`useScreen`, `useGrid`), and plugin usage was updated.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure `const screen = useScreen()` and `const grid = useGrid()` are placed directly inside your component's `setup()` method or a custom composable.","message":"When using `vue-screen` with the Composition API, `useScreen` and `useGrid` must be called within a component's `setup()` function or another valid Composition API context. Calling them outside will result in an error.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"When installing the plugin, specify the exact configuration string: `createApp().use(VueScreen, 'bootstrap-v5')` or `useGrid('bootstrap-v5')` if a specific version endpoint is provided.","message":"If using the plugin version with global properties (`$screen`, `$grid`), ensure you pass the correct breakpoint configuration name (e.g., 'bootstrap', 'tailwind', 'bulma') during plugin installation, especially for UI frameworks that have multiple versions (e.g., Bootstrap 4 vs. 5).","severity":"gotcha","affected_versions":">=2.3.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the plugin is globally installed: `createApp(App).use(VueScreen, 'bootstrap').mount('#app')`.","cause":"Attempting to access `$screen` or `$grid` properties in a component without registering `vue-screen` as a plugin in your `createApp` chain.","error":"TypeError: Cannot read properties of undefined (reading 'width') / Cannot read property 'width' of undefined"},{"fix":"Move the calls to `useScreen()` and `useGrid()` inside the `setup()` function of your Vue component.","cause":"Attempting to call `useScreen()` or `useGrid()` outside of a Vue 3 component's `setup()` function or a custom composable.","error":"Invalid hook call. Hooks can only be called inside of the setup() function."},{"fix":"Extend Vue's `ComponentCustomProperties` interface in a declaration file (e.g., `shims-vue.d.ts`):\n```typescript\nimport '@vue/runtime-core';\nimport type { Screen, Grid } from 'vue-screen';\n\ndeclare module '@vue/runtime-core' {\n  interface ComponentCustomProperties {\n    $screen: Screen;\n    $grid: Grid;\n  }\n}\n```","cause":"TypeScript might not correctly infer the global properties (`$screen`, `$grid`) added by the `vue-screen` plugin.","error":"Property '$screen' does not exist on type 'ComponentPublicInstance<{}, {}, {}, {}, {}, {}, {}, {}, false, ComponentOptionsBase<any, any, any, any, any, any, any, any, any, {}>>'."}],"ecosystem":"npm"}