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 モジュールはコンポーザブルを自動インポートするため、手動でインポートは不要です。

カテゴリ

カテゴリ	例
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

クイックリファレンス

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

作業内容	読み込むファイル
コンポーザブルを検索	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) {
  // ブラウザ専用コード
  const { width } = useWindowSize()
}

onMounted でラップする:

const width = ref(0)

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

SSR 安全なコンポーザブルを使用する:

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

@vueuse/nuxt は SSR を自動処理します - コンポーザブルはサーバー上で安全なデフォルト値を返します。

ターゲット要素 Ref

DOM 要素ではなくコンポーネント ref をターゲットにする場合:

import type { MaybeElementRef } from '@vueuse/core' // ❌ 機能しません

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

// コンポーネント ref は .$el で DOM 要素を取得する必要があります
const compRef = ref<ComponentInstance>()
const { width } = useElementSize(compRef)

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)
})