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:

bash
1pnpm add @vueuse/core

Nuxt:

bash
1pnpm add @vueuse/nuxt @vueuse/core

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

Nuxt module auto-imports composables - no import needed.

Categories

Quick Reference

Load composable files based on what you need:

Loading Files

Consider loading these reference files based on your task:

• references/composables.md - if searching for VueUse composables by category or functionality

DO NOT load all files at once. Load only what's relevant to your current task.

Common Patterns

State persistence:

ts
1const state = useLocalStorage('my-key', { count: 0 })

Mouse tracking:

ts
1const { x, y } = useMouse()

Debounced ref:

ts
1const search = ref('')
2const debouncedSearch = refDebounced(search, 300)

Shared composable (singleton):

ts
1const useSharedMouse = createSharedComposable(useMouse)

SSR Gotchas

Many VueUse composables use browser APIs unavailable during SSR.

Check with isClient:

ts
1import { isClient } from '@vueuse/core'
2
3if (isClient) {
4  // Browser-only code
5  const { width } = useWindowSize()
6}

Wrap in onMounted:

ts
1const width = ref(0)
2
3onMounted(() => {
4  // Only runs in browser
5  const { width: w } = useWindowSize()
6  width.value = w.value
7})

Use SSR-safe composables:

ts
1// These check isClient internally
2const mouse = useMouse() // Returns {x: 0, y: 0} on server
3const 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:

ts
1import type { MaybeElementRef } from '@vueuse/core' // ❌ Won't work
2
3// Use MaybeElementRef pattern
4import { unrefElement } from '@vueuse/core'
5
6// Component ref needs .$el to get DOM element
7const compRef = ref<ComponentInstance>()
8const { width } = useElementSize(compRef)
9
10const el = computed(() => unrefElement(compRef)) // Gets .$el
11const { width } = useElementSize(el) // ✅ Works

Or access $el directly:

ts
1const compRef = ref<ComponentInstance>()
2
3onMounted(() => {
4  const el = compRef.value?.$el as HTMLElement
5  const { width } = useElementSize(el)
6})