Registry / web-framework / vue-screen-utils

vue-screen-utils

JSON →
library1.0.0-beta.13jsnpmunverified

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.

npm install vue-screen-utils
INSTALL
IMPORT
SIG · VUE-SCREEN-UTILS
V
vue-screen-utils
web-frameworkjavascriptv1.0.0-beta.13
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

useScreens
import { useScreens } from 'vue-screen-utils'
const { useScreens } = require('vue-screen-utils')
Primary composable for defining screen breakpoints and injecting utilities. Prefer named imports for tree-shaking.
inject
import { inject } from 'vue'
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.
Screens
import type { Screens } from 'vue-screen-utils'
TypeScript type for the object returned by `useScreens` and injected into child components. Useful for type safety with `inject`.

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.

// App.vue (Parent component where screens are configured) <script setup lang="ts"> import { useScreens } from 'vue-screen-utils'; import ChildComponent from './ChildComponent.vue'; // Assume this file exists and is imported // Configure screen breakpoints. This call also automatically 'provides' the screen utilities // under the key '$screens' (or a custom injectKey if specified). useScreens({ xs: '0px', // Example: (min-width: 0px) sm: '640px', md: '768px', lg: '1024px', xl: '1280px' }); </script> <template> <div style="font-family: sans-serif; padding: 20px;"> <h1>Parent Component</h1> <p>This component sets up the global screen utilities.</p> <ChildComponent /> </div> </template> // ChildComponent.vue (Child component accessing screen utilities) <script setup lang="ts"> import { inject, computed } from 'vue'; import type { Screens } from 'vue-screen-utils'; // Inject the screens object that was provided by the parent via useScreens. // Type assertion `!` can be used if you're certain it will be injected, or handle `null`. const $screens = inject<Screens>('$screens'); // Defensive check for robustness, especially in complex applications if (!$screens) { console.error("Screen utilities not injected. Ensure useScreens is called in an ancestor."); // In a real application, you might provide fallback values or throw an error. } // Access reactive screen properties and utility functions const currentScreen = computed(() => $screens?.current.value || 'N/A'); const isLargeScreen = computed(() => $screens?.matches.lg || false); const mappedValue = computed(() => $screens?.mapCurrent({ xs: 0, sm: 1, md: 2, lg: 3, xl: 4 }, 0).value || 0 ); </script> <template> <div style="border: 1px solid #ccc; padding: 15px; margin-top: 20px;"> <h2>Child Component</h2> <p>Resize your browser window to see reactive updates:</p> <p>Current screen: <strong>{{ currentScreen }}</strong></p> <p>Is 'large' (>=1024px): <strong>{{ isLargeScreen }}</strong></p> <p>Mapped value for current screen: <strong>{{ mappedValue }}</strong></p> <p v-if="currentScreen === 'xl'" style="color: #007bff;">You're on an extra-large screen!</p> </div> </template>
Debug
Known issues
breakingAs 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.
fix
Consult the changelog for specific migration instructions when updating between beta versions.
affects: >=1.0.0-beta.0
gotchaWhen 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.
fix
Ensure your screen configuration object keys correspond to progressively larger `min-width` values, starting with a mobile-first `0px`.
affects: >=1.0.0-beta.0
gotchaTo 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`.
fix
Ensure `useScreens()` is invoked in a parent component higher up in the component tree before attempting to `inject('$screens')` in any descendant component.
affects: >=1.0.0-beta.0
gotchaBy 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()`.
fix
Match the `inject` key in child components to the `injectKey` option used during `useScreens` configuration in the parent.
affects: >=1.0.0-beta.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'value') or (reading 'md')
Attempting to access properties like `.current.value` or `.matches.md` on the `$screens` object when it is `undefined` because `inject('$screens')` failed.
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');`
Module not found: Error: Can't resolve 'vue-screen-utils' in '...'
The `vue-screen-utils` package has not been installed or there's a typo in the import path.
fix
Run `npm install vue-screen-utils` or `yarn add vue-screen-utils`. Double-check the import statement for typos.
Argument of type '{ min: string; }' is not assignable to parameter of type 'string | string[] | Record<string, string | MediaValue | MediaValue[]>'.
Incorrect format or type provided in the configuration object to `useScreens` when defining custom screen breakpoints, particularly with TypeScript.
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.
Upgrade
Version history
1.0.0-beta.13latest on npm
Audit
Dependencies
vuerequiredPeer dependency, required for all Vue 3 applications using this library.
Agent activity
10 hits · last 30 days
node
8
Amazon
1
OpenAI (training)
1
Resources
vue-screen-utils — npm install vue-screen-utils · libregistry