# VueUse: a decision guide to the Vue Composition utility collection

> VueUse is an MIT-licensed TypeScript collection of Vue 3 composition utilities, published as @vueuse/core and installed with npm. It suits teams that want reactive browser, state and sensor helpers without writing them, and it is the wrong tool if you need a state management framework rather than a set of composables.

**vueuse/vueuse** — Collection of essential Vue Composition Utilities for Vue 3

- Repository: https://github.com/vueuse/vueuse
- Website: https://vueuse.org
- Stars: 22,383 · Forks: 2,949
- Language: TypeScript
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/vueuse-vueuse

## What VueUse solves, and who it is written for

VueUse is a collection of Vue Composition Utilities for Vue 3. The problem it addresses is narrow but recurring: a Vue application needs reactive access to something outside Vue's own reactivity system, such as pointer coordinates, the user's colour-scheme preference, or a value persisted in localStorage. Each of those is a small amount of code, and each has edge cases around server rendering, cleanup and event targets. VueUse packages those patterns as composables you import instead of write.

The audience is Vue 3 developers working in TypeScript. The README lists the intended properties: fully tree shakeable, type strong, SSR friendly, usable via CDN with no bundler, configurable event filters and targets, and optional add-ons for Router, Firebase and RxJS. That combination points at application teams rather than library authors. If you are building a component library that must stay dependency-light, pulling in a utility collection is a decision you make once and then live with.

## How the composables are structured and what happens at runtime

The README's usage example shows the shape of the API. You import named functions from @vueuse/core, call them at the top of a setup function, and destructure reactive values back out. useMouse returns x and y, usePreferredDark returns a boolean that tracks the user's colour-scheme preference, and useLocalStorage takes a key plus a default value and returns a ref-like object that persists to localStorage.

The repository is a pnpm workspace monorepo. The top-level package.json is private and named @vueuse/monorepo, with packages built through turbo and the documentation built with VitePress from the packages directory. The README separates @vueuse/shared from @vueuse/core in the CDN example, and the add-ons page covers integrations that are not part of the core package. That split matters when you reason about what you are pulling in: core is the main entry point, shared holds the underlying primitives, and integrations are separate.

Two mechanisms are worth calling out because they shape how you use the library. Tree shaking means unused composables should not reach your bundle, so importing from the package root is intended to be safe. Configurable event filters and targets mean composables that listen to events expose control over what they listen to and where, rather than hard-coding window.

## Installing VueUse and a first working component

The README gives a single install command. It assumes a Vue 3 project with a package manager already configured.

```bash
npm i @vueuse/core
```

Version thresholds are stated in the README and are the first thing to check. From v14.0, VueUse requires Vue v3.5 or newer. From v13.0 it required Vue v3.3 or newer. From v12.0 it no longer supports Vue 2, and the README directs Vue 2 users to v11.x. The current release line is v15.0.0, published on 2026-09-16, so a new install will land on 15.x and needs Vue 3.5 or newer.

The README's own usage snippet is the shortest real example. It imports three composables, reads mouse coordinates, checks the dark-theme preference, and persists an object under a localStorage key.

```ts
import { useLocalStorage, useMouse, usePreferredDark } from '@vueuse/core'

const { x, y } = useMouse()

// if user prefers dark theme
const isDark = usePreferredDark()

const store = useLocalStorage(
  'my-storage',
  {
    name: 'Apple',
    color: 'red',
  },
)
```

What you should see: x and y update as the pointer moves, isDark reflects the browser preference and reacts to changes, and store survives a page reload because it writes through to localStorage under the key my-storage. The README points to the functions list and the documentation site for the full set, and lists starter repositories for Vite, Nuxt 3 and Webpack if you want a working project rather than a snippet.

If you cannot use a bundler, the README documents a CDN path: load @vueuse/shared and @vueuse/core as script tags from unpkg, after which the library is exposed globally as window.VueUse.

## Where VueUse stops being the right dependency

The most common mismatch is treating VueUse as state management. It is not. useLocalStorage persists a value to browser storage, and the search results show people comparing VueUse's createGlobalState with Pinia, but the README describes VueUse as a utility collection and does not present it as a store with devtools, module registration, or a defined pattern for large application state. If your problem is shared application state across routes, a dedicated state library is the tool, and VueUse is at most a helper inside it.

The second constraint is the Vue version floor. The README is explicit that v12.0 dropped Vue 2 support, so a Vue 2 codebase cannot use current VueUse at all. That is a version boundary, not a configuration issue. Similarly, v14.0 raised the requirement to Vue 3.5 or newer, so a project pinned to an older Vue 3 minor has to stay on an older VueUse line or upgrade Vue first.

The third is scope creep. Every composable you import is code you did not write and now have to keep current. Tree shaking limits the bundle cost, not the upgrade cost. The README links to an export-size page, which is the right place to check what a given composable actually adds before you assume it is free.

## VueUse versus lodash and versus a state library

The comparison the search data keeps returning is VueUse against lodash. The difference in approach is reactivity. lodash is a general-purpose JavaScript utility library: you call a function, it returns a value, and if you want that value to update in a Vue template you wire up the reactivity yourself. VueUse composables are built on Vue's reactivity system, so useMouse returns refs that track the pointer without you writing a watcher. That is why VueUse cannot be dropped into a non-Vue project and why lodash still has a place for pure data transformation.

Against Pinia, the difference is purpose rather than mechanism. Pinia defines stores: named, registered units of shared state with an established pattern for reading and writing them across a component tree. VueUse gives you composables, including createGlobalState for a shared reactive value, but it does not impose a store structure. If you want a single reactive object shared between two components and nothing more, a VueUse composable is less ceremony. If you want stores, actions, and a consistent convention across a large app, the store library is the right layer.

VueUse is also not the only composable collection. The README credits react-use, vue-hooks, vue-use-web and react-hooks as inspirations, which places it in a family of hook libraries rather than as an original idea. Its distinguishing properties, per the README, are the TypeScript typing, SSR friendliness, tree shakeability and the add-on packages.

## Maintenance, releases and the MIT licence

VueUse is not archived, and the last push was on 2026-09-19, two days before the date used here. The release cadence visible in the release list is roughly every two to three months on the minor line, with v14.3.0 on 2026-05-01, v14.4.0 on 2026-07-29, and v15.0.0 on 2026-09-16. A major version bump is the signal that matters for upgrade cost, because the README's version notes show that VueUse uses majors to change the Vue requirement and to drop support, as v12.0 and v14.0 did. Budget for reading the release notes at each major, not at each minor.

The repository requires Node 22 or newer for development, uses pnpm 11.25.0 as the package manager, and runs its test suite through Vitest with separate browser, unit and server projects. That is relevant only if you intend to contribute or fork; consuming the package does not require any of it.

The licence is MIT, held by Anthony Fu, with the LICENSE file at the repository root. MIT permits commercial use and modification with the copyright notice retained. This is an observation about the licence text, not legal advice; if your organisation has licence policy, route it through whoever handles that.

## Conclusion

Adopt VueUse if you are on Vue 3.5 or newer and want ready-made composables for browser state, storage and sensors rather than hand-rolling them. Do not adopt it as a replacement for a state management layer, and do not expect Vue 2 support: the README states that from v12.0 VueUse no longer supports Vue 2 and points to v11.x for that. Before installing, check your Vue version against the release thresholds in the README, and read the export-size page if bundle budget is tight, since tree shaking only helps if you import the specific composables you use.

## FAQ

### How do I install VueUse?

Install the core package with npm i @vueuse/core. The README states that from v14.0 VueUse requires Vue 3.5 or newer, and that from v12.0 Vue 2 is no longer supported, with v11.x recommended for Vue 2 projects.

### How do I install VueUse core?

The README gives npm i @vueuse/core as the install command for the core package. It also documents a CDN alternative that loads @vueuse/shared and @vueuse/core from unpkg and exposes the library as window.VueUse.

### What is VueUse core?

@vueuse/core is the main package of the VueUse collection of Vue Composition Utilities for Vue 3. The README's usage example imports useLocalStorage, useMouse and usePreferredDark from it.

### Is VueUse good?

That depends on what you need. The README lists tree shakeability, TypeScript typing, SSR friendliness and CDN usage as properties, and the repository is not archived with a last push on 2026-09-19, but the README does not present VueUse as a state management solution, so it is a poor fit if that is the gap you are filling.

### What is the difference between VueUse and Pinia?

Pinia provides stores, while VueUse provides individual composables, including createGlobalState for a shared reactive value. If you need defined stores with a consistent convention across an application, VueUse is not a substitute for that layer.

## Sources

- [License: MIT](https://github.com/vueuse/vueuse/blob/main/LICENSE)
- [Project website](https://vueuse.org)
- [README](https://github.com/vueuse/vueuse/blob/main/README.md)
- [Releases](https://github.com/vueuse/vueuse/releases)
- [vueuse/vueuse on GitHub](https://github.com/vueuse/vueuse)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vueuse-vueuse