{"id":12569,"library":"vue-screen-utils","title":"Vue Screen Utilities","description":"vue-screen-utils is a dependency-free Vue 3 library providing a suite of reactive utility functions for managing screen breakpoints, media queries, DOM element resize observations, and dark mode detection. Currently in version `1.0.0-beta.13`, it is in active development with a stable `1.0.0` release anticipated soon, implying a potentially frequent update cadence until then. The library is fully written in TypeScript, offering robust type safety and excellent IDE support. It distinguishes itself by allowing developers to define custom, semantically named screen size keys (e.g., `sm`, `md`, `lg`) and map them to various media query formats, which are then reactively evaluated against the current viewport. It offers both composable functions like `useScreens`, `useMediaQuery`, `useResizeObserver`, and `useDarkMode`, as well as a plugin for application-wide integration. Key features include a reactive `matches` object indicating active breakpoints, a `current` computed property for the largest active screen key, and utility functions like `mapCurrent` and `mapList` for mapping custom values to the current screen state.","status":"active","version":"1.0.0-beta.13","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install vue-screen-utils","lang":"bash","label":"npm"},{"cmd":"yarn add vue-screen-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-screen-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, required for all Vue 3 applications using this library.","package":"vue","optional":false}],"imports":[{"note":"Primary composable for defining screen breakpoints and injecting utilities. Prefer named imports for tree-shaking.","wrong":"const { useScreens } = require('vue-screen-utils')","symbol":"useScreens","correct":"import { useScreens } from 'vue-screen-utils'"},{"note":"Used in child components to access the '$screens' object provided by an ancestor. It's a core Vue import, but essential for this library's typical usage pattern.","symbol":"inject","correct":"import { inject } from 'vue'"},{"note":"TypeScript type for the object returned by `useScreens` and injected into child components. Useful for type safety with `inject`.","symbol":"Screens","correct":"import type { Screens } from 'vue-screen-utils'"}],"quickstart":{"code":"// App.vue (Parent component where screens are configured)\n<script setup lang=\"ts\">\nimport { useScreens } from 'vue-screen-utils';\nimport ChildComponent from './ChildComponent.vue'; // Assume this file exists and is imported\n\n// Configure screen breakpoints. This call also automatically 'provides' the screen utilities\n// under the key '$screens' (or a custom injectKey if specified).\nuseScreens({\n  xs: '0px', // Example: (min-width: 0px)\n  sm: '640px',\n  md: '768px',\n  lg: '1024px',\n  xl: '1280px'\n});\n</script>\n\n<template>\n  <div style=\"font-family: sans-serif; padding: 20px;\">\n    <h1>Parent Component</h1>\n    <p>This component sets up the global screen utilities.</p>\n    <ChildComponent />\n  </div>\n</template>\n\n\n// ChildComponent.vue (Child component accessing screen utilities)\n<script setup lang=\"ts\">\nimport { inject, computed } from 'vue';\nimport type { Screens } from 'vue-screen-utils';\n\n// Inject the screens object that was provided by the parent via useScreens.\n// Type assertion `!` can be used if you're certain it will be injected, or handle `null`.\nconst $screens = inject<Screens>('$screens');\n\n// Defensive check for robustness, especially in complex applications\nif (!$screens) {\n  console.error(\"Screen utilities not injected. Ensure useScreens is called in an ancestor.\");\n  // In a real application, you might provide fallback values or throw an error.\n}\n\n// Access reactive screen properties and utility functions\nconst currentScreen = computed(() => $screens?.current.value || 'N/A');\nconst isLargeScreen = computed(() => $screens?.matches.lg || false);\nconst mappedValue = computed(() =>\n  $screens?.mapCurrent({ xs: 0, sm: 1, md: 2, lg: 3, xl: 4 }, 0).value || 0\n);\n</script>\n\n<template>\n  <div style=\"border: 1px solid #ccc; padding: 15px; margin-top: 20px;\">\n    <h2>Child Component</h2>\n    <p>Resize your browser window to see reactive updates:</p>\n    <p>Current screen: <strong>{{ currentScreen }}</strong></p>\n    <p>Is 'large' (>=1024px): <strong>{{ isLargeScreen }}</strong></p>\n    <p>Mapped value for current screen: <strong>{{ mappedValue }}</strong></p>\n    <p v-if=\"currentScreen === 'xl'\" style=\"color: #007bff;\">You're on an extra-large screen!</p>\n  </div>\n</template>","lang":"typescript","description":"This quickstart demonstrates how to set up `vue-screen-utils` in a parent component using `useScreens` and then consume the reactive screen utilities in a child component via Vue's `inject` API. It shows how to access the current screen, check active breakpoints, and map custom values."},"warnings":[{"fix":"Consult the changelog for specific migration instructions when updating between beta versions.","message":"As of version `1.0.0-beta.13`, the library is still in beta. While APIs are generally stable, minor breaking changes might occur before the official 1.0.0 stable release. Always review release notes when upgrading between beta versions.","severity":"breaking","affected_versions":">=1.0.0-beta.0"},{"fix":"Ensure your screen configuration object keys correspond to progressively larger `min-width` values, starting with a mobile-first `0px`.","message":"When defining screen sizes with `useScreens`, it is strongly recommended to order them from smallest to largest (e.g., `xs: '0px'`, `sm: '640px'`, `md: '768px'`). The internal logic often relies on this order for determining the 'current' active screen.","severity":"gotcha","affected_versions":">=1.0.0-beta.0"},{"fix":"Ensure `useScreens()` is invoked in a parent component higher up in the component tree before attempting to `inject('$screens')` in any descendant component.","message":"To use the `inject('$screens')` method in a child component, an ancestor component (typically a root or parent) must first call `useScreens()` to provide the screen utilities. If `useScreens` is not called, `inject('$screens')` will return `undefined`.","severity":"gotcha","affected_versions":">=1.0.0-beta.0"},{"fix":"Match the `inject` key in child components to the `injectKey` option used during `useScreens` configuration in the parent.","message":"By default, `useScreens` injects its utilities using the key `'$screens'`. If you specify a custom `injectKey` in the `useScreens` options (e.g., `{ injectKey: '$myScreens' }`), child components must use the exact same custom key when calling `inject()`.","severity":"gotcha","affected_versions":">=1.0.0-beta.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `useScreens()` is called in an ancestor component. Add a check for `$screens` being `null` or `undefined` after `inject()` to handle cases where it might not be provided, e.g., `const currentScreen = computed(() => $screens?.current.value || 'default');`","cause":"Attempting to access properties like `.current.value` or `.matches.md` on the `$screens` object when it is `undefined` because `inject('$screens')` failed.","error":"TypeError: Cannot read properties of undefined (reading 'value') or (reading 'md')"},{"fix":"Run `npm install vue-screen-utils` or `yarn add vue-screen-utils`. Double-check the import statement for typos.","cause":"The `vue-screen-utils` package has not been installed or there's a typo in the import path.","error":"Module not found: Error: Can't resolve 'vue-screen-utils' in '...'"},{"fix":"Refer to the `useScreens` documentation for the correct `config` object format, ensuring that values are `string`, `string[]`, `{ min: string }`, `{ max: string }`, or arrays of these, matching the `MediaValue` type definition.","cause":"Incorrect format or type provided in the configuration object to `useScreens` when defining custom screen breakpoints, particularly with TypeScript.","error":"Argument of type '{ min: string; }' is not assignable to parameter of type 'string | string[] | Record<string, string | MediaValue | MediaValue[]>'."}],"ecosystem":"npm"}