vueuse

VueUse

不可欠な Vue Composition ユーティリティのコレクションです。カスタムコンポーザブルを書く前に VueUse を確認してください。ほとんどのパターンはすでに実装されています。

現在の安定版： Vue 3.5 以降向けの VueUse 14.x

インストール

Vue 3：

pnpm add @vueuse/core

Nuxt：

pnpm add @vueuse/nuxt @vueuse/core

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

Nuxt モジュールがコンポーザブルを自動インポートするため、インポートは不要です。

カテゴリー

カテゴリー	例
状態	useLocalStorage, useSessionStorage, useRefHistory
要素	useElementSize, useIntersectionObserver, useResizeObserver
ブラウザー	useClipboard, useFullscreen, useMediaQuery
センサー	useMouse, useKeyboard, useDeviceOrientation
ネットワーク	useFetch, useWebSocket, useEventSource
アニメーション	useTransition, useInterval, useTimeout
コンポーネント	useVModel, useVirtualList, useTemplateRefsList
ウォッチ	watchDebounced, watchThrottled, watchOnce
リアクティビティ	createSharedComposable, toRef, toReactive
配列	useArrayFilter, useArrayMap, useSorted
時間	useDateFormat, useNow, useTimeAgo
ユーティリティ	useDebounce, useThrottle, useMemoize

クイックリファレンス

必要なものに応じてコンポーザブルのファイルを読み込みます。

作業内容	ファイルを読み込む
コンポーザブルを探す	references/composables.md
特定のコンポーザブル	composables/<name>.md

ファイルの読み込み

タスクに応じて、次のリファレンスファイルを読み込むことを検討してください。

• references/composables.md - カテゴリーまたは機能別に VueUse のコンポーザブルを探す場合

すべてのファイルを一度に読み込まないでください。 現在のタスクに関連するものだけを読み込んでください。

よくあるパターン

状態の永続化：

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

マウスの追跡：

const { x, y } = useMouse()

デバウンス付き ref：

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

共有コンポーザブル（シングルトン）：

const useSharedMouse = createSharedComposable(useMouse)

SSR に関する注意点

多くの VueUse コンポーザブルは、SSR 中に使用できないブラウザー API を使用します。

isClient で確認：

import { isClient } from '@vueuse/core'

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

onMounted でラップ：

const width = ref(0)

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

SSR セーフなコンポーザブルを使用：

// 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 が SSR を自動処理します - コンポーザブルはサーバー上で安全なデフォルト値を返します。

対象要素の参照

DOM 要素ではなくコンポーネントの参照を対象にする場合：

import 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

または $el に直接アクセス：

const compRef = ref<ComponentInstance>()

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