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-utilsVerified import paths — ran on the pinned version, not inferred.
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.
Consult the changelog for specific migration instructions when updating between beta versions.
Ensure your screen configuration object keys correspond to progressively larger `min-width` values, starting with a mobile-first `0px`.
Ensure `useScreens()` is invoked in a parent component higher up in the component tree before attempting to `inject('$screens')` in any descendant component.Match the `inject` key in child components to the `injectKey` option used during `useScreens` configuration in the parent.
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');`
Run `npm install vue-screen-utils` or `yarn add vue-screen-utils`. Double-check the import statement for typos.
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.