VueUse

Vue Composition API のための必須ユーティリティコレクション。カスタム composable を書く前に 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 モジュールが composable を自動的にインポートします。import は不要です。

カテゴリー

カテゴリー	例
State	useLocalStorage, useSessionStorage, useRefHistory
Elements	useElementSize, useIntersectionObserver, useResizeObserver
Browser	useClipboard, useFullscreen, useMediaQuery
Sensors	useMouse, useKeyboard, useDeviceOrientation
Network	useFetch, useWebSocket, useEventSource
Animation	useTransition, useInterval, useTimeout
Component	useVModel, useVirtualList, useTemplateRefsList
Watch	watchDebounced, watchThrottled, watchOnce
Reactivity	createSharedComposable, toRef, toReactive
Array	useArrayFilter, useArrayMap, useSorted
Time	useDateFormat, useNow, useTimeAgo
Utilities	useDebounce, useThrottle, useMemoize

クイックリファレンス

必要に応じて composable ファイルを読み込みます:

作業内容	ファイルを読み込む
composable を探す	references/composables.md
特定の composable	composables/<name>.md

ファイルの読み込み

タスクに基づいて以下のリファレンスファイルを読み込むことを検討してください:

• references/composables.md - VueUse composable をカテゴリーまたは機能で検索する場合

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

共通パターン

状態の永続化:

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

マウス位置の追跡:

const { x, y } = useMouse()

デバウンスされた ref:

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

共有 composable (シングルトン):

const useSharedMouse = createSharedComposable(useMouse)

SSR に関する注意点

多くの VueUse composable は SSR 中には利用できないブラウザ API を使用しています。

isClient で確認:

import { isClient } from '@vueuse/core'

if (isClient) {
  // ブラウザ限定のコード
  const { width } = useWindowSize()
}

onMounted でラップ:

const width = ref(0)

onMounted(() => {
  // ブラウザ内でのみ実行
  const { width: w } = useWindowSize()
  width.value = w.value
})

SSR 対応の composable を使用:

// これらは内部的に isClient をチェック
const mouse = useMouse() // サーバー上では {x: 0, y: 0} を返す
const storage = useLocalStorage('key', 'default') // サーバー上ではデフォルト値を使用

@vueuse/nuxt は SSR を自動的に処理します - composable はサーバー上で安全なデフォルト値を返します。

ターゲット要素 Ref

DOM 要素の代わりにコンポーネント ref をターゲットにする場合:

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

// コンポーネント ref は DOM 要素を取得するために .$el が必要
const compRef = ref<ComponentInstance>()
const { width } = useElementSize(compRef) // ❌ 動作しません

// MaybeElementRef パターンを使用
import { unrefElement } from '@vueuse/core'

const el = computed(() => unrefElement(compRef)) // .$el を取得
const { width } = useElementSize(el) // ✅ 動作します

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

const compRef = ref<ComponentInstance>()

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