Vue 3 Composition APIの使い方｜早見表と実行結果

Composition APIとは、ref や computed などの関数を組み合わせて、コンポーネントの状態とロジックを書くVue 3の書き方です。 現在は <script setup> と組み合わせて使うのが標準で、export default { data() {...} } のような枠を書かずに、変数と関数をそのまま並べるだけでテンプレートから使えます。

この記事では、Vue 3.5.43（2026年9月時点の最新安定版）+ Vite 8.3.1 で、よく使うAPIをすべて <script setup> 形式のコピペで動くコードにまとめました。さらに、ブラウザ（Chromium）で実際にボタンを押して画面の値を読み取った結果を載せています。「分割代入するとリアクティブでなくなる」「watch と watchEffect の実行タイミングの違い」なども、実行結果で確かめられます。最後に、リリース候補版の Vue 3.6（3.6.0-rc.9）の Vapor Mode を実際にビルドしてサイズを比較しています。

Composition APIの早見表

<script setup> では defineProps / defineEmits / defineModel はimport不要です（コンパイラが処理するマクロのため）。それ以外の ref や watch は import { ... } from 'vue' で読み込みます。

Options APIとの対応表

Options API（data / methods などのオプションで書く従来の書き方）から移る方向けに、対応をまとめます。どちらもVue 3で公式にサポートされている書き方で、同じプロジェクト内で混在もできます。

いちばん大きな違いは「関連するロジックを1か所にまとめられる」ことです。Options APIでは1つの機能のコードが data・computed・methods・watch に分かれますが、Composition APIでは機能ごとに上から並べて書けて、そのまま関数（composable）に切り出せます。

検証環境と動かし方

以下のバージョンで実行しています。

新規プロジェクトは公式の npm create vue@latest で作るのが手軽です。この記事の検証では、仕組みがわかるように最小構成を手で作りました。

npm init -y
npm i vue
npm i -D vite @vitejs/plugin-vue

// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({ plugins: [vue()] })

// src/main.js
import { createApp } from 'vue'
import App from './App.vue'

createApp(App).mount('#app')

index.html に <div id="app"></div> と <script type="module" src="/src/main.js"></script> を書き、npx vite で起動します。

ref と reactive で状態を持つ

コピペ用コード

<!-- src/components/Counter.vue -->
<script setup>
import { ref, reactive, computed, toRefs } from 'vue'

const count = ref(0)                                   // プリミティブは ref
const task = reactive({ title: '備品発注', done: 0 })  // オブジェクトは reactive も可

// 分割代入：リアクティブが失われる
let { done } = task
// toRefs で分割代入：リアクティブが保たれる
const { done: doneRef } = toRefs(task)

const label = computed(() => `${task.title}：${task.done}件完了`)

function add() {
  count.value++   // script 内では .value が必要
  task.done++     // reactive は .value 不要
}
</script>

<template>
  <section>
    <button id="add" @click="add">+1</button>
    <p id="count">count: {{ count }}</p>
    <p id="done">task.done: {{ task.done }}</p>
    <p id="destructured">分割代入 done: {{ done }}</p>
    <p id="torefs">toRefs doneRef: {{ doneRef }}</p>
    <p id="label">{{ label }}</p>
  </section>
</template>

実行結果（「+1」を2回クリック）

Chromiumで画面を開き、ボタンを2回押したあとの表示をそのまま読み取りました。

--- 初期表示
#count => count: 0
#done => task.done: 0
#destructured => 分割代入 done: 0
#torefs => toRefs doneRef: 0
#label => 備品発注：0件完了
--- +1 を2回クリック後
#count => count: 2
#done => task.done: 2
#destructured => 分割代入 done: 0
#torefs => toRefs doneRef: 2
#label => 備品発注：2件完了

let { done } = task で取り出した done だけが 0 のままです。分割代入はその時点の値（数値の0）をコピーするだけなので、元の task との結びつきがなくなります。toRefs(task) を通すと、各プロパティが ref になって結びつきが保たれ、2 に更新されました。

また、テンプレート内では ref の .value は自動で外れるため、{{ count }} と書けば中身が表示されます。.value が必要なのは <script> の中だけです。

ref と reactive の使い分け判断表

迷ったら ref に統一するのがわかりやすい選び方です。公式ドキュメントも、reactive の制約（再代入・分割代入）を理由に ref を主に使うことを勧めています。フォームのように「まとまったオブジェクトを項目ごとに更新する」場面では reactive も読みやすく書けます。

computed で値を計算する

import { ref, computed } from 'vue'

const items = ref([{ name: 'ノート', qty: 2 }, { name: 'ペン', qty: 5 }])
const total = computed(() => items.value.reduce((s, i) => s + i.qty, 0))
// total.value → 7。items が変わると自動で再計算される

computed は依存する値が変わったときだけ再計算され、結果がキャッシュされます。 テンプレートで関数を呼ぶ（{{ calcTotal() }}）と再描画のたびに実行されるので、計算結果を表示する用途には computed が向いています。書き込みもしたい場合は computed({ get() {...}, set(v) {...} }) の形にします。

watch と watchEffect で変化に反応する

コピペ用コード

<!-- src/components/Watchers.vue -->
<script setup>
import { ref, watch, watchEffect } from 'vue'

const keyword = ref('')
const logs = ref([])

watch(keyword, (newVal, oldVal) => {
  logs.value.push(`watch: "${oldVal}" -> "${newVal}"`)
})

watchEffect(() => {
  // 中で読んだ keyword を自動で追跡。登録直後にも1回実行される
  logs.value.push(`watchEffect: "${keyword.value}"`)
})
</script>

<template>
  <input id="kw" v-model="keyword" />
  <ul id="logs"><li v-for="(l, i) in logs" :key="i">{{ l }}</li></ul>
</template>

実行結果（入力欄に「ab」を入力）

[ 'watchEffect: ""', 'watch: "" -> "ab"', 'watchEffect: "ab"' ]

watchEffect は登録した直後に1回実行され、watch は値が変わるまで実行されません。 また watch は変更前と変更後の値を受け取れます。

reactive のプロパティを監視するときは getter で渡す

import { reactive, watch } from 'vue'

const task = reactive({ done: 0 })
watch(task.done, (v) => console.log('A', v))            // 数値の 0 を渡している
watch(() => task.done, (v) => console.log('B: done =', v)) // getter で渡す
task.done++

Node.jsで実行した結果です（開発モード）。

[Vue warn]: Invalid watch source:  0 A watch source can only be a getter/effect function, a ref, a reactive object, or an array of these types.
B: done = 1

task.done と書くとその瞬間の数値が渡るため監視できません。() => task.done のように関数で渡すと動きます。

ライフサイクルと useTemplateRef で DOM に触る

<script setup>
import { ref, onMounted, useTemplateRef } from 'vue'

const inputEl = useTemplateRef('search')  // Vue 3.5 以降
const lifecycle = ref([])

onMounted(() => {
  inputEl.value.focus()
  lifecycle.value.push(`onMounted: focus=${document.activeElement === inputEl.value}`)
})
</script>

<template>
  <input ref="search" id="search" />
  <p id="lifecycle">{{ lifecycle.join(',') }}</p>
</template>

実行結果です。

#lifecycle => onMounted: focus=true

DOM要素は onMounted の時点で取得できます。 <script setup> の直下（マウント前）では inputEl.value は null です。useTemplateRef はVue 3.5で追加されたAPIで、3.4以前は const search = ref(null) と同名の変数を用意する書き方をします（3.5でも動きます）。

props・emits・defineModel で親子をつなぐ

子コンポーネント

<!-- src/components/Child.vue -->
<script setup>
const props = defineProps({
  title: { type: String, required: true },
  stock: { type: Number, default: 0 },
})
const emit = defineEmits(['order'])
const note = defineModel('note', { default: '' })
</script>

<template>
  <div>
    <p id="child-title">{{ props.title }}（在庫 {{ stock }}）</p>
    <button id="order" @click="emit('order', props.title)">発注</button>
    <input id="note" v-model="note" />
  </div>
</template>

親コンポーネント

<script setup>
import { ref } from 'vue'
import Child from './components/Child.vue'

const ordered = ref('')
const memo = ref('初期メモ')
</script>

<template>
  <Child title="コピー用紙" :stock="3" @order="t => ordered = t" v-model:note="memo" />
  <p id="ordered">発注: {{ ordered }}</p>
  <p id="memo">親のmemo: {{ memo }}</p>
</template>

実行結果（「発注」をクリックし、子の入力欄に「至急」と入力）

#memo => 親のmemo: 初期メモ        ← 初期表示
#ordered => 発注: コピー用紙       ← emit で親に届いた
#memo => 親のmemo: 至急            ← defineModel で親の memo が更新された

defineModel（Vue 3.4以降）を使うと、子で note.value = ... するだけで親の v-model の値が更新されます。 以前は props + emit('update:note', v) を組み合わせて書く必要がありました。

TypeScriptでは型で宣言できます。

const props = defineProps<{ title: string; stock?: number }>()
const emit = defineEmits<{ order: [title: string] }>()
const note = defineModel<string>('note', { default: '' })

Vue 3.5からは const { title, stock = 0 } = defineProps<...>() のように props を分割代入してもリアクティブが保たれ、既定値もこの形で書けます（Reactive Props Destructure）。ただし分割代入した変数を watch するときは watch(() => stock, ...) のように getter で渡します。

provide / inject で離れたコンポーネントに渡す

<!-- 親（App.vue） -->
<script setup>
import { provide } from 'vue'
provide('theme', 'dark')
</script>

<!-- 子孫（Theme.vue） -->
<script setup>
import { inject } from 'vue'
const theme = inject('theme', 'light')          // 第2引数は見つからないときの既定値
const missing = inject('notProvided', '既定値')
</script>
<template><p id="inject">theme: {{ theme }} / missing: {{ missing }}</p></template>

実行結果です。

#inject => theme: dark / missing: 既定値

provide に ref を渡すと、子孫側でも変更に追従します。 子孫から値を書き換えられたくないときは provide('theme', readonly(theme)) のように readonly で包み、変更用の関数を別に provide するとデータの流れが追いやすくなります。

composable でロジックを再利用する

composable（コンポーザブル）は、Composition APIを使った状態とロジックをまとめた関数です。名前は use で始めるのが慣例です。

// src/composables/useCounter.js
import { ref, computed } from 'vue'

export function useCounter(initial = 0) {
  const count = ref(initial)
  const double = computed(() => count.value * 2)
  const increment = () => { count.value++ }
  const reset = () => { count.value = initial }
  return { count, double, increment, reset }
}

<script setup>
import { useCounter } from './composables/useCounter'
const { count: c2, double, increment } = useCounter(10)
</script>

<template>
  <button id="inc" @click="increment">composable +1</button>
  <p id="composable">{{ c2 }} / {{ double }}</p>
</template>

実行結果（クリック前 → 1回クリック後）です。

#composable => 10 / 20
#composable => 11 / 22

composable から ref を返しておくと、呼び出し側で分割代入しても値が追従します。 これが「迷ったら ref」をおすすめする理由の1つです。コンポーネントごとに useCounter() を呼べば、それぞれ独立した状態を持ちます。

よくあるつまずきと直し方

Vue 3.6 の Vapor Mode を試す（リリース候補版）

Vapor Mode は、仮想DOMを使わずにテンプレートを直接DOM操作のコードへコンパイルする、Vue 3.6で追加予定の新しい描画方式です。2026年9月時点では 3.6.0-rc.9（リリース候補版） で、npmの latest は3.5.43です。本番採用は安定版の公開を待ち、検証用に試すのがおすすめです。

公式のリリースノートによると、有効化は次のとおりです。

• <script setup vapor> と書く（Composition APIの <script setup> またはテンプレートのみのSFCが対象。Options APIは非対応）
• すべてVaporコンポーネントなら createVaporApp() でアプリを作ると、仮想DOMのランタイムを含まずに済む
• 既存の createApp() のアプリに混ぜる場合は vaporInteropPlugin を登録する

同じ画面をビルドしてサイズを比較

リストに項目を追加して合計を表示する同じコンポーネントを、通常版と Vapor 版でビルドしました。

<!-- App.vue（Vapor 版は 1行目を <script setup vapor> にする） -->
<script setup>
import { ref, computed } from 'vue'
const items = ref([{ id: 1, name: 'ノート', qty: 2 }, { id: 2, name: 'ペン', qty: 5 }])
const total = computed(() => items.value.reduce((s, i) => s + i.qty, 0))
const add = () => items.value.push({ id: Date.now(), name: '付箋', qty: 1 })
</script>
<template>
  <button id="add" @click="add">追加</button>
  <ul><li v-for="i in items" :key="i.id">{{ i.name }} × {{ i.qty }}</li></ul>
  <p id="total">合計 {{ total }}</p>
</template>

// main.js（Vapor 版）
import { createVaporApp } from 'vue'
import App from './App.vue'
createVaporApp(App).mount('#app')

npm i vue@3.6.0-rc.9 のあと @vitejs/plugin-vue@6.0.9 を入れると、peerDependencies（vue@"^3.2.25"）がプレリリース版に一致せず ERESOLVE になりました。検証では --legacy-peer-deps を付けて入れています。

vite build（Vite 8.3.1）の出力です。

== 通常版（createApp + <script setup>）
dist/assets/index-BTE8xCbK.js  65.45 kB │ gzip: 25.55 kB
== Vapor 版（createVaporApp + <script setup vapor>）
dist/assets/index-BNcBgcMm.js  48.48 kB │ gzip: 18.48 kB

この小さな画面では、Vapor版のJSがgzip後で約7kB小さくなりました。 どちらもChromiumで「追加」を押すと 合計 8 になり、リストに「付箋 × 1」が加わることを確認しています（エラーなし）。サイズの差は主にランタイムの違いなので、コンポーネントが増えたときの比率は画面の構成によって変わります。

Composition APIと <script setup> で書いておくと、Vapor Modeへの切り替えは属性の追加が中心になります。 これから書くコードを <script setup> にそろえておく価値は大きいといえます。

よくある質問

Q. Options APIとComposition API、どちらを使えばよいですか？ A. どちらも公式にサポートされています。新規で書くなら、ロジックの再利用や型推論のしやすさから <script setup> + Composition APIが選ばれることが多いです。Vapor ModeもComposition API（<script setup>）が対象です。既存のOptions APIのコードは、そのまま動かしながら少しずつ移せます。

Q. setup() 関数と <script setup> の違いは何ですか？ A. <script setup> は setup() 関数を短く書くための構文です。setup() では使う値を return で返す必要がありますが、<script setup> ではトップレベルの変数や関数がそのままテンプレートで使えます。

Q. ref と reactive はどちらを使えばよいですか？ A. 迷ったら ref に統一するとわかりやすくなります。reactive は再代入や分割代入で結びつきが切れるため、使うときは toRefs や Object.assign とあわせて使います。

Q. Vuex の代わりに composable だけで状態共有できますか？ A. composable の外（モジュールのトップ）で ref を作れば、複数コンポーネントで共有できます。ただしSSRや開発ツールとの連携を考えると、アプリ全体の状態は公式推奨の Pinia を使うと管理しやすくなります。

まとめ

• Composition APIは <script setup> と組み合わせ、変数と関数を並べて書くのが標準
• script 内では .value、テンプレートでは不要。迷ったら ref に統一
• reactive の分割代入は結びつきが切れる（実行結果で 0 のまま）→ toRefs で解決
• watchEffect は登録直後に実行、watch は変化時のみ。reactive のプロパティは getter で watch
• 親子は defineProps / defineEmits / defineModel、離れた階層は provide / inject
• 再利用は ref を返す composable にまとめる
• Vue 3.6 rc の Vapor Mode は今回の画面で gzip 約28%減。安定版の公開を待って採用を検討

株式会社RJCでは、Vueの新しい書き方や描画方式の変化を、実際に手を動かして確かめながらプロジェクトの中で共有しています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。