---

name: vueuse description: Use when working with VueUse composables - provides reactive utilities for state, browser APIs, sensors, network, animations. Check VueUse before writing custom composables - most patterns already implemented. license: MIT

VueUse

Collection of essential Vue Composition utilities. Check VueUse before writing custom composables - most patterns already implemented.

Current stable: VueUse 14.x for Vue 3.5+

Installation

Vue 3:

Copypnpm add @vueuse/core

Nuxt:

Copypnpm add @vueuse/nuxt @vueuse/core

Copy// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@vueuse/nuxt'],
})

Nuxt module auto-imports composables - no import needed.

Categories

Quick Reference

Load composable files based on what you need:

Loading Files

Start with references/composables.md to find the right composable.

Then load the specific composable file for detailed usage: composables/use-mouse.md, composables/use-local-storage.md, etc.

DO NOT load all files at once - wastes context on irrelevant patterns.

Common Patterns

State persistence:

Copyconst state = useLocalStorage('my-key', { count: 0 })

Mouse tracking:

Copyconst { x, y } = useMouse()

Debounced ref:

Copyconst search = ref('')
const debouncedSearch = refDebounced(search, 300)

Shared composable (singleton):

Copyconst useSharedMouse = createSharedComposable(useMouse)

SSR Gotchas

Many VueUse composables use browser APIs unavailable during SSR.

Check with isClient:

Copyimport { isClient } from '@vueuse/core'

if (isClient) {
  // Browser-only code
  const { width } = useWindowSize()
}

Wrap in onMounted:

Copyconst width = ref(0)

onMounted(() => {
  // Only runs in browser
  const { width: w } = useWindowSize()
  width.value = w.value
})

Use SSR-safe composables:

Copy// These check isClient internally
const mouse = useMouse() // Returns {x: 0, y: 0} on server
const storage = useLocalStorage('key', 'default') // Uses default on server

@vueuse/nuxt auto-handles SSR - composables return safe defaults on server.

Target Element Refs

When targeting component refs instead of DOM elements:

Copyimport type { MaybeElementRef } from '@vueuse/core'

// Component ref needs .$el to get DOM element
const compRef = ref<ComponentInstance>()
const { width } = useElementSize(compRef) // ❌ Won't work

// Use MaybeElementRef pattern
import { unrefElement } from '@vueuse/core'

const el = computed(() => unrefElement(compRef)) // Gets .$el
const { width } = useElementSize(el) // ✅ Works

Or access $el directly:

Copyconst compRef = ref<ComponentInstance>()

onMounted(() => {
  const el = compRef.value?.$el as HTMLElement
  const { width } = useElementSize(el)
})