Vue 3 Composition API — A Complete Guide

Vue 3's Composition API is often presented as the new way to write components, which makes people think the Options API is deprecated. It is not. The Composition API exists to solve a specific problem the Options API handles poorly — sharing stateful logic between components and keeping related logic together in large components. Understanding what problem it solves is the key to using it well rather than cargo-culting it everywhere.

The problem it solves

In the Options API, a component's logic is split across data, methods, computed, and watch. For a simple component that is fine and readable. For a complex one, a single feature's logic gets scattered across those options, and reusing that logic between components meant awkward mixins with naming collisions. The Composition API lets you group a feature's logic together and extract it into a reusable function — a composable — cleanly.

The building blocks

Inside setup (or <script setup>), you build reactive state from a few primitives:

import { ref, computed } from 'vue'

const count = ref(0)                          // reactive primitive
const double = computed(() => count.value * 2) // derived, cached
function increment() { count.value++ }         // .value in JS, not in template

Use ref for individual reactive values (accessed via .value in script, unwrapped in the template), reactive for reactive objects, and computed for derived values that cache until their dependencies change. <script setup> is the ergonomic syntax that removes most of the boilerplate and is what you should reach for in new Vue 3 code.

Composables are the payoff

The real value arrives when you extract logic into a composable — a function, conventionally named useSomething, that encapsulates reactive state and behaviour and returns it. A useMouse, usePagination, or useFetch composable is reusable across any component with no mixin collisions, and it is just a function, so it is testable and composable with other composables. This clean logic reuse is the entire point of the API.

The Vue 3 Composition API is the better tool for organising complex component logic and — through composables — reusing it cleanly, built on ref, reactive, and computed inside <script setup>. Use it where its strengths pay off, keep the Options API for the simple cases where it reads fine, and let composables be the reason you reach for it rather than fashion.