⚙️ Composition API Fundamentals

Why the Composition API?

The Composition API is a set of functions — ref, computed, watch, the on* hooks — that you call to build a component's logic. It exists to solve a real pain in the older Options API: as a component grows, the code for one feature gets smeared across separate data, methods, computed, and watch sections, forcing you to scroll around to understand a single behavior.

💡 A useful analogy: The Options API sorts your belongings by type — all cables in one drawer, all chargers in another, all manuals in a third. The Composition API sorts by purpose — everything for your camera in one box, everything for your laptop in another. When you need the camera, you grab one box instead of raiding three drawers.

The Options API organizes by option type; the Composition API keeps each feature's code together.

script setup

The <script setup> block is the modern, compile-time-optimized entry point for the Composition API. Every top-level binding you declare — variables, functions, imported components — is automatically available in the template. No return statement, no boilerplate.

<template>
  <p>Count: {{ count }}</p>
  <p>Double: {{ doubleCount }}</p>
  <button @click="increment">Increment</button>
</template>

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

const count = ref(0)
const doubleCount = computed(() => count.value * 2)

function increment() {
  count.value++
}

onMounted(() => console.log('mounted'))
// Everything above is auto-exposed to the template
</script>

ref and reactive

Reactivity is the engine that re-renders your UI when data changes. The Composition API gives you two ways to create reactive state.

ref() — a reactive box for any value

ref() wraps a value in a reactive container with a single .value property. It works for primitives and objects. You read and write .value in JavaScript, but in templates Vue unwraps it for you automatically.

import { ref } from 'vue'

const count = ref(0)
console.log(count.value)   // 0
count.value++              // reactive update
console.log(count.value)   // 1

const user = ref({ name: 'Ada', age: 30 })
user.value.age = 31        // still reactive

💡 What is a ref, really? Think of a museum display case. The case itself stays put, but when you swap the artifact inside, sensors notice and update the information panel. A ref is that case: .value is the artifact, and Vue is the sensor that refreshes the UI whenever it changes.

reactive() — a deeply reactive object

reactive() makes an entire object reactive with no .value needed. It only works on objects, arrays, and collections — not primitives.

import { reactive } from 'vue'

const state = reactive({
  name: 'Ada',
  address: { city: 'London' }
})

state.name = 'Grace'            // reactive
state.address.city = 'New York' // nested changes are reactive too

Which should I use?

const state = reactive({ name: 'Ada', age: 30 })
let { name } = state   // ❌ 'name' is now a plain, non-reactive string

import { reactive, toRefs } from 'vue'

const state = reactive({ name: 'Ada', age: 30 })
const { name, age } = toRefs(state)
name.value = 'Grace'   // ✅ updates state.name

Computed Properties

computed() creates derived state — a value calculated from other reactive values that updates automatically and caches its result until a dependency changes.

import { ref, computed } from 'vue'

const firstName = ref('Grace')
const lastName = ref('Hopper')

const fullName = computed(() => `${firstName.value} ${lastName.value}`)

console.log(fullName.value)   // 'Grace Hopper'
firstName.value = 'Ada'
console.log(fullName.value)   // 'Ada Hopper' — recalculated automatically

Writable computed

Pass an object with get and set to make a computed writable — handy when a single derived value maps back onto several sources:

const fullName = computed({
  get() {
    return `${firstName.value} ${lastName.value}`
  },
  set(value) {
    const parts = value.split(' ')
    firstName.value = parts[0]
    lastName.value = parts[parts.length - 1]
  }
})

fullName.value = 'Katherine Johnson'
console.log(firstName.value)  // 'Katherine'
console.log(lastName.value)   // 'Johnson'

Watchers

Where computed produces a value, a watcher runs a side effect — fetching data, writing to localStorage, logging — in response to changes.

watch: react to a specific source

import { ref, watch } from 'vue'

const query = ref('')
const results = ref([])

watch(query, async (newQuery, oldQuery) => {
  if (!newQuery.trim()) {
    results.value = []
    return
  }
  const res = await fetch(`/api/search?q=${encodeURIComponent(newQuery)}`)
  results.value = await res.json()
})

You can watch multiple sources at once, watch deeply for nested changes, or run immediately on setup:

// Watch several sources
watch([firstName, lastName], ([newFirst, newLast]) => {
  console.log(`Name is now ${newFirst} ${newLast}`)
})

// Deep watch a reactive object + run once immediately
watch(user, (value) => save(value), { deep: true, immediate: true })

watchEffect: track dependencies automatically

watchEffect runs immediately and re-runs whenever any reactive value it used changes — you never list dependencies explicitly.

import { ref, watchEffect } from 'vue'

const userId = ref(1)
const userData = ref(null)

watchEffect(async () => {
  // userId.value is read here, so this re-runs whenever it changes
  const res = await fetch(`/api/users/${userId.value}`)
  userData.value = await res.json()
})

userId.value = 2   // triggers the effect again

Lifecycle & Template Refs

The Composition API exposes lifecycle hooks as imported on* functions. There's no onCreated — the top level of <script setup> is the creation phase.

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

// Code here runs during creation (replaces beforeCreate/created)

onMounted(() => {
  console.log('DOM is ready')
})

onBeforeUnmount(() => {
  console.log('cleaning up before removal')
})
</script>

Template refs

To reach an actual DOM element, declare a ref whose name matches the element's ref attribute. It's null until the component mounts, so access it inside onMounted.

<template>
  <input ref="inputEl" />
  <button @click="focusInput">Focus</button>
</template>

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

const inputEl = ref(null)

onMounted(() => {
  inputEl.value.focus()   // the element exists now
})

function focusInput() {
  inputEl.value.focus()
}
</script>

Composables: Reusing Logic

The headline payoff of the Composition API is the composable: a plain function that uses Composition-API primitives to package stateful logic so you can reuse it across components. By convention, composables are named useSomething.

💡 A useful analogy: Composables are like kitchen appliances. A blender does one job well and shows up in many recipes. Extract "counting" or "fetching" into a composable once, and every component can plug it in without re-implementing it.

Writing a composable

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

export function useCounter(initial = 0, step = 1) {
  const count = ref(initial)
  const doubled = computed(() => count.value * 2)

  function increment() { count.value += step }
  function decrement() { count.value -= step }
  function reset()     { count.value = initial }

  return { count, doubled, increment, decrement, reset }
}

Using it in a component

<template>
  <p>Count: {{ count }} (doubled: {{ doubled }})</p>
  <button @click="increment">+</button>
  <button @click="decrement">-</button>
  <button @click="reset">Reset</button>
</template>

<script setup>
import { useCounter } from './composables/useCounter'

const { count, doubled, increment, decrement, reset } = useCounter(10, 2)
</script>

A more useful example: useFetch

// composables/useFetch.js
import { ref, watchEffect, toValue, isRef } from 'vue'

export function useFetch(url) {
  const data = ref(null)
  const error = ref(null)
  const loading = ref(false)

  async function run() {
    loading.value = true
    error.value = null
    try {
      const res = await fetch(toValue(url))   // accepts a ref OR a string
      if (!res.ok) throw new Error(`HTTP ${res.status}`)
      data.value = await res.json()
    } catch (err) {
      error.value = err.message
    } finally {
      loading.value = false
    }
  }

  // If url is reactive, re-fetch when it changes; otherwise fetch once
  if (isRef(url)) watchEffect(run)
  else run()

  return { data, error, loading, refresh: run }
}

Hands-on Exercise

// composables/useToggle.js
import { ref } from 'vue'

export function useToggle(initial = false) {
  const state = ref(initial)
  const toggle = () => { state.value = !state.value }
  const setOn  = () => { state.value = true }
  const setOff = () => { state.value = false }
  return { state, toggle, setOn, setOff }
}

<template>
  <button @click="toggleDetails">
    {{ showDetails ? 'Hide' : 'Show' }} details
  </button>
  <p v-if="showDetails">Here are the details!</p>

  <button @click="toggleDark">Toggle dark mode</button>
  <p>Dark mode is {{ dark ? 'on' : 'off' }}</p>
</template>

<script setup>
import { useToggle } from './composables/useToggle'

// Two independent instances — no duplicated logic
const { state: showDetails, toggle: toggleDetails } = useToggle()
const { state: dark, toggle: toggleDark } = useToggle(false)
</script>

Best Practices

Summary & Quiz

📚 Further Reading

• Vue.js — Composition API FAQ
• Vue.js — Reactivity Fundamentals
• Vue.js — Composables
• VueUse — a large collection of ready-made composables

🚀 What's Next?

You've now covered Vue's core. Next we pivot to the other framework in this module: Angular Framework Architecture — a look at how Angular structures an application with standalone components, signals, and dependency injection.