Reactive Screen Size and Media Queries for Vue 3

2.4.2 · active · verified Sun Apr 19

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.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'width') / Cannot read property 'width' of undefined
```
cause Attempting to access `$screen` or `$grid` properties in a component without registering `vue-screen` as a plugin in your `createApp` chain.

fix Ensure the plugin is globally installed: `createApp(App).use(VueScreen, 'bootstrap').mount('#app')`.
```
Invalid hook call. Hooks can only be called inside of the setup() function.
```
cause Attempting to call `useScreen()` or `useGrid()` outside of a Vue 3 component's `setup()` function or a custom composable.

fix Move the calls to `useScreen()` and `useGrid()` inside the `setup()` function of your Vue component.
```
Property '$screen' does not exist on type 'ComponentPublicInstance<{}, {}, {}, {}, {}, {}, {}, {}, false, ComponentOptionsBase<any, any, any, any, any, any, any, any, any, {}>>'.
```
cause TypeScript might not correctly infer the global properties (`$screen`, `$grid`) added by the `vue-screen` plugin.

fix Extend Vue's `ComponentCustomProperties` interface in a declaration file (e.g., `shims-vue.d.ts`): ```typescript import '@vue/runtime-core'; import type { Screen, Grid } from 'vue-screen'; declare module '@vue/runtime-core' { interface ComponentCustomProperties { $screen: Screen; $grid: Grid; } } ```

Warnings

breaking 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.
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.
breaking 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.
Fix: Refer to the official upgrading guide in the documentation (https://reegodev.github.io/vue-screen/guide/upgrading) for detailed migration steps.
gotcha 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.
Fix: Ensure `const screen = useScreen()` and `const grid = useGrid()` are placed directly inside your component's `setup()` method or a custom composable.
gotcha 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).
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.

Install

npm install vue-screen npm
yarn add vue-screen yarn
pnpm add vue-screen pnpm

Imports

useScreen
wrong:
```
const useScreen = require('vue-screen').useScreen
```
correct:
```
import { useScreen } from 'vue-screen'
```
This is a Composition API hook. VueScreen v2 is ESM-first and requires Vue 3.
useGrid
wrong:
```
import useGrid from 'vue-screen'
```
correct:
```
import { useGrid } from 'vue-screen'
```
A Composition API hook used for accessing UI framework grid breakpoints. Takes an optional framework name (e.g., 'bulma').
VueScreen
wrong:
```
import { VueScreen } from 'vue-screen'
```
correct:
```
import VueScreen from 'vue-screen'
```
This is the default export for the plugin installation, typically used with the Options API.

Quickstart

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.

import { createApp } from 'vue'
import { useScreen, useGrid } from 'vue-screen'
import VueScreen from 'vue-screen'

const App = {
  setup() {
    const screen = useScreen();
    const grid = useGrid('tailwind'); // Or 'bootstrap', 'bulma', etc.

    return {
      screen,
      grid
    };
  },
  template: `
    <div>
      <h1>VueScreen Demo</h1>
      <p>Window Width: {{ screen.width }}px</p>
      <p>Window Height: {{ screen.height }}px</p>
      <p>Current Breakpoint: {{ grid.breakpoint }}</p>
      <p>Is Mobile: {{ grid.isMobile }}</p>
      <p>Is Desktop: {{ grid.isDesktop }}</p>
      <p>Orientation: {{ screen.orientation }}</p>
    </div>
  `
};

// Option 1: Using Composition API directly in a component (as shown above)
// Note: For global access or Options API, use as a plugin:
const app = createApp(App);
app.use(VueScreen, 'bootstrap'); // Installs as a plugin with Bootstrap breakpoints
app.mount('#app');

// You can inspect the global properties with Options API in a child component:
// <template>
//   <ul>
//     <li>Current breakpoint is: {{ $grid.breakpoint }}</li>
//     <li>Window width is: {{ $screen.width }}</li>
//   </ul>
// </template>

view raw JSON →