Vueuse

1---2name: vueuse3description: Use when working with VueUse composables - track mouse position with useMouse, manage localStorage with useStorage, detect network status with useNetwork, debounce values with refDebounced, and access browser APIs reactively. Check VueUse before writing custom composables - most patterns already implemented.4license: MIT5---6 7# VueUse8 9Collection of essential Vue Composition utilities. Check VueUse before writing custom composables - most patterns already implemented.10 11**Current stable:** VueUse 14.x for Vue 3.5+12 13## Installation14 15**Vue 3:**16 17```bash18pnpm add @vueuse/core19```20 21**Nuxt:**22 23```bash24pnpm add @vueuse/nuxt @vueuse/core25```26 27```ts28// nuxt.config.ts29export default defineNuxtConfig({30  modules: ['@vueuse/nuxt'],31})32```33 34Nuxt module auto-imports composables - no import needed.35 36## Categories37 38| Category   | Examples                                                   |39| ---------- | ---------------------------------------------------------- |40| State      | useLocalStorage, useSessionStorage, useRefHistory          |41| Elements   | useElementSize, useIntersectionObserver, useResizeObserver |42| Browser    | useClipboard, useFullscreen, useMediaQuery                 |43| Sensors    | useMouse, useKeyboard, useDeviceOrientation                |44| Network    | useFetch, useWebSocket, useEventSource                     |45| Animation  | useTransition, useInterval, useTimeout                     |46| Component  | useVModel, useVirtualList, useTemplateRefsList             |47| Watch      | watchDebounced, watchThrottled, watchOnce                  |48| Reactivity | createSharedComposable, toRef, toReactive                  |49| Array      | useArrayFilter, useArrayMap, useSorted                     |50| Time       | useDateFormat, useNow, useTimeAgo                          |51| Utilities  | useDebounce, useThrottle, useMemoize                       |52 53## Quick Reference54 55Load composable files based on what you need:56 57| Working on...        | Load file                                              |58| -------------------- | ------------------------------------------------------ |59| Finding a composable | [references/composables.md](references/composables.md) |60| Specific composable  | `composables/<name>.md`                                |61 62## Loading Files63 64**Consider loading these reference files based on your task:**65 66- [ ] [references/composables.md](references/composables.md) - if searching for VueUse composables by category or functionality67 68**DO NOT load all files at once.** Load only what's relevant to your current task.69 70## Common Patterns71 72**State persistence:**73 74```ts75const state = useLocalStorage('my-key', { count: 0 })76```77 78**Mouse tracking:**79 80```ts81const { x, y } = useMouse()82```83 84**Debounced ref:**85 86```ts87const search = ref('')88const debouncedSearch = refDebounced(search, 300)89```90 91**Shared composable (singleton):**92 93```ts94const useSharedMouse = createSharedComposable(useMouse)95```96 97## SSR Gotchas98 99Many VueUse composables use browser APIs unavailable during SSR.100 101**Check with `isClient`:**102 103```ts104import { isClient } from '@vueuse/core'105 106if (isClient) {107  // Browser-only code108  const { width } = useWindowSize()109}110```111 112**Wrap in onMounted:**113 114```ts115const width = ref(0)116 117onMounted(() => {118  // Only runs in browser119  const { width: w } = useWindowSize()120  width.value = w.value121})122```123 124**Use SSR-safe composables:**125 126```ts127// These check isClient internally128const mouse = useMouse() // Returns {x: 0, y: 0} on server129const storage = useLocalStorage('key', 'default') // Uses default on server130```131 132**`@vueuse/nuxt` auto-handles SSR** - composables return safe defaults on server.133 134## Target Element Refs135 136When targeting component refs instead of DOM elements:137 138```ts139import type { MaybeElementRef } from '@vueuse/core'140 141// Component ref needs .$el to get DOM element142const compRef = ref<ComponentInstance>()143const { width } = useElementSize(compRef) // ❌ Won't work144 145// Use MaybeElementRef pattern146import { unrefElement } from '@vueuse/core'147 148const el = computed(() => unrefElement(compRef)) // Gets .$el149const { width } = useElementSize(el) // ✅ Works150```151 152**Or access `$el` directly:**153 154```ts155const compRef = ref<ComponentInstance>()156 157onMounted(() => {158  const el = compRef.value?.$el as HTMLElement159  const { width } = useElementSize(el)160})161```