{"id":15902,"library":"vue-component-media-queries","title":"Vue Component Media Queries","description":"Vue Component Media Queries is a lightweight library (less than 1kb gzipped) that provides Vue 2 components for integrating the `window.matchMedia` API directly into your templates and script logic. It is currently at a stable v1.0.0 release. The library differentiates itself by being highly optimized for server-side rendering (SSR), specifically tested with Nuxt.js to prevent hydration errors and support predictive rendering, making it suitable for complex responsive layouts where CSS alone might lead to performance issues or require logic. While there isn't an explicit release cadence, the library has moved from several alpha versions to a stable 1.0.0, suggesting a focus on stability for its current major version. It offers flexibility by allowing media queries to be defined globally via a `MediaQueryProvider` or used for single queries with `MatchMedia`, and can also inject query states into components.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/CyberAP/vue-component-media-queries","tags":["javascript","vue","responsive","media","media-queries","breakpoints","match-media","ssr","nuxt","typescript"],"install":[{"cmd":"npm install vue-component-media-queries","lang":"bash","label":"npm"},{"cmd":"yarn add vue-component-media-queries","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-component-media-queries","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, explicitly supports Vue 2.6.0+","package":"vue","optional":false}],"imports":[{"note":"Used to define global media queries for consumption by child components. Primarily designed for ES Modules. If using CDN, it's available as `VueComponentMediaQueries.MediaQueryProvider`.","wrong":"const { MediaQueryProvider } = require('vue-component-media-queries')","symbol":"MediaQueryProvider","correct":"import { MediaQueryProvider } from 'vue-component-media-queries'"},{"note":"A renderless component that consumes defined media queries via a scoped slot to reactively render content based on current viewport size. Best used with ES Modules. For CDN, access as `VueComponentMediaQueries.MatchMedia`.","wrong":"const { MatchMedia } = require('vue-component-media-queries')","symbol":"MatchMedia","correct":"import { MatchMedia } from 'vue-component-media-queries'"},{"note":"While not a direct JS import, `mediaQueries` is an injected property provided by `MediaQueryProvider`. It grants script access to the reactive state of defined media queries, allowing for logic-based adaptations outside of templates.","wrong":"import { mediaQueries } from 'vue-component-media-queries'","symbol":"mediaQueries (injection)","correct":"export default {\n  inject: ['mediaQueries']\n}"}],"quickstart":{"code":"<template>\n  <div id=\"app\">\n    <h1>Responsive Layout Example</h1>\n    <p>Resize your browser window to see the layout adapt.</p>\n\n    <MediaQueryProvider :queries=\"{\n      mobile: '(max-width: 680px)',\n      tablet: '(min-width: 681px) and (max-width: 1024px)',\n      desktop: '(min-width: 1025px)'\n    }\">\n      <MatchMedia v-slot=\"{ mobile, tablet, desktop }\">\n        <div :class=\"{\n          'layout-box': true,\n          'mobile-layout': mobile,\n          'tablet-layout': tablet,\n          'desktop-layout': desktop\n        }\">\n          <h2 v-if=\"mobile\">Mobile Layout</h2>\n          <h2 v-else-if=\"tablet\">Tablet Layout</h2>\n          <h2 v-else-if=\"desktop\">Desktop Layout</h2>\n          <h2 v-else>Default Layout</h2>\n          <p>This content changes based on media queries.</p>\n          <p>Current state: {{ mobile ? 'Mobile' : (tablet ? 'Tablet' : (desktop ? 'Desktop' : 'Unknown')) }}</p>\n        </div>\n      </MatchMedia>\n    </MediaQueryProvider>\n  </div>\n</template>\n\n<script lang=\"ts\">\nimport Vue from 'vue';\nimport { MediaQueryProvider, MatchMedia } from 'vue-component-media-queries';\n\nexport default Vue.extend({\n  name: 'App',\n  components: {\n    MediaQueryProvider,\n    MatchMedia,\n  },\n});\n</script>\n\n<style>\n#app {\n  font-family: Avenir, Helvetica, Arial, sans-serif;\n  text-align: center;\n  color: #2c3e50;\n  margin-top: 60px;\n}\n.layout-box {\n  border: 1px solid #42b983;\n  padding: 20px;\n  margin: 20px auto;\n  max-width: 800px;\n  box-shadow: 0 2px 8px rgba(0,0,0,0.1);\n  transition: all 0.3s ease;\n}\n.mobile-layout { background-color: #e0f7fa; color: #00796b; }\n.tablet-layout { background-color: #fffde7; color: #fbc02d; }\n.desktop-layout { background-color: #e8f5e9; color: #388e3c; }\n</style>","lang":"typescript","description":"This example demonstrates how to set up global media queries using `MediaQueryProvider` and reactively consume their states within a child `MatchMedia` component. It shows a basic responsive layout changing based on mobile, tablet, or desktop viewport sizes."},"warnings":[{"fix":"For Vue 3 projects, seek an alternative `matchMedia` integration library compatible with Vue 3's composition API or consider implementing custom `matchMedia` logic.","message":"This library is exclusively designed for Vue 2 applications (peer dependency `^2.6.0`). It is not compatible with Vue 3 due to breaking API changes between Vue major versions.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always evaluate if a CSS-only solution (e.g., `@media` rules) is sufficient before introducing `vue-component-media-queries`. Reserve this library for logic-dependent responsive behaviors or performance-critical conditional rendering.","message":"The library integrates `window.matchMedia` and should not be used for simple style changes that can be handled with pure CSS media queries. Using this library when CSS is sufficient can introduce unnecessary JavaScript overhead and complexity.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Thoroughly test SSR behavior with your specific framework (e.g., Nuxt.js). Ensure `fallback` props are set appropriately to provide an initial matching state during server render, which can prevent flickering or mismatches on client-side hydration.","message":"While the library boasts strong SSR support and claims no hydration errors, complex SSR setups or incorrect initial `fallback` prop configurations on `MediaQueryProvider` or `MatchMedia` can still lead to hydration mismatches or unexpected behavior.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always prefer installing via NPM (`npm i vue-component-media-queries`) and importing components as ES Modules. This ensures optimal bundling, tree-shaking, and dependency management for production environments.","message":"The documentation explicitly states that the CDN method for including the library is 'not recommended for production usage'. Relying on a global `VueComponentMediaQueries` object can lead to versioning issues, lack of tree-shaking, and slower load times compared to a modern module bundler setup.","severity":"gotcha","affected_versions":">=1.0.0-alpha.7"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure `MatchMedia` or any component injecting `mediaQueries` is a descendant of a `MediaQueryProvider` component that has defined the necessary queries.","cause":"Attempting to use `MatchMedia` or `this.mediaQueries` injection without a parent `MediaQueryProvider` component in the component tree.","error":"Error in render: 'mediaQueries' is not defined"},{"fix":"Set the `ssr` prop on `MediaQueryProvider` or `MatchMedia` to `true` (or a specific boolean value) and ensure `fallback` props are correctly configured to provide a default state during SSR, preventing `window.matchMedia` from being called on the server.","cause":"This error typically occurs in a server-side rendering (SSR) environment where `window` is not available, and a `matchMedia` related function is invoked without proper SSR guards or `ssr` prop configuration.","error":"Cannot read properties of undefined (reading 'matchMedia')"},{"fix":"Import the component (`import { MediaQueryProvider } from 'vue-component-media-queries'`) and add it to your Vue component's `components` object: `components: { MediaQueryProvider }`.","cause":"The `MediaQueryProvider` or `MatchMedia` component was used in a template but not correctly imported and registered in the Vue component's `components` option.","error":"[Vue warn]: Unknown custom element: <MediaQueryProvider> - did you register the component correctly?"}],"ecosystem":"npm"}