Vue 3 Composition API

Quick Guide: Use

<script setup>

for all components.

ref()

for primitives,

reactive()

for objects. Extract reusable logic into composables (

use*

functions). Clean up side effects in

onUnmounted

. Use

defineModel()

for v-model (3.4+),

useTemplateRef()

for DOM refs (3.5+),

onWatcherCleanup()

to cancel stale async work (3.5+). Destructured props require getter wrappers in

watch()

.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,

import type

, named constants)

(You MUST use

<script setup>

(You MUST clean up all side effects (timers, listeners, subscriptions) in

onUnmounted

(You MUST use

ref()

reactive()

.value

(You MUST prefix all composable functions with

use

(You MUST wrap destructured props in a getter for

watch()

watch(() => count, ...)

watch(count, ...)

</critical_requirements>

Auto-detection: Vue 3 Composition API, script setup, ref, reactive, computed, watch, watchEffect, composables, onMounted, onUnmounted, defineProps, defineEmits, defineExpose, defineModel, useTemplateRef, useId, onWatcherCleanup, provide, inject, Suspense

When to use:

• Building Vue 3 components using Composition API
• Creating reusable composables (use* functions)
• Managing reactive state with ref/reactive
• Handling component lifecycle and side effects
• TypeScript integration with Vue components

Key patterns covered:

• Script setup syntax and compiler macros (defineProps, defineEmits, defineExpose)
• Reactivity primitives (ref, reactive, computed, watch, watchEffect)
• Composables pattern for logic reuse
• defineModel() for v-model binding (Vue 3.4+)
• useTemplateRef(), useId(), onWatcherCleanup() (Vue 3.5+)
• Reactive props destructure with getter requirement (Vue 3.5+)
• Provide/Inject for dependency injection
• Async components and Suspense

When NOT to use:

• Components that don't benefit from logic extraction
• When team has no Composition API experience (consider gradual adoption)

Philosophy

The Composition API enables organizing code by logical concern rather than by option type (data, methods, computed). This makes complex components more maintainable and enables powerful logic reuse through composables.

Core principles:

1. Composition over configuration - Group related logic together instead of splitting across options
2. Explicit reactivity - State is explicitly reactive via

   ref()

   and

   reactive()

3. Logic reuse via composables - Extract and share stateful logic between components
4. TypeScript-first - Types flow naturally without excessive annotations

Core Patterns

Pattern 1: Script Setup with Props and Emits

All variables/functions in

<script setup>

defineProps

defineEmits

<script setup lang="ts">
import { ref, computed } from "vue";

const props = defineProps<{
  userId: string;
  initialCount?: number;
}>();

const emit = defineEmits<{
  update: [value: number];
  submit: [];
}>();

const count = ref(props.initialCount ?? 0);
const doubleCount = computed(() => count.value * 2);

function increment() {
  count.value++;
  emit("update", count.value);
}
</script>

Why good: No explicit return needed, TypeScript types flow naturally, named tuple emit syntax (Vue 3.3+) self-documents payloads

See examples/core.md for a complete component with loading/error handling.

Pattern 2: Reactivity - ref vs reactive

ref()

reactive()

.value

const count = ref(0); // Primitive -> ref
count.value++; // .value in script

const state = reactive({
  // Nested object -> reactive
  user: null as User | null,
  settings: { theme: "light" },
});
state.settings.theme = "dark"; // Direct access, no .value

Gotcha: Destructuring

reactive()

toRefs(state)

See examples/reactivity.md for ref/reactive/computed patterns and anti-patterns.

Pattern 3: Watch and WatchEffect

Skip if using Nuxt — use useFetch or useAsyncData instead.

watch()

watchEffect()

onWatcherCleanup()

// watch: explicit source, access to old value
watch(searchQuery, async (newQuery, oldQuery) => {
  /* ... */
});

// watchEffect: auto-tracks dependencies, runs immediately
watchEffect(async () => {
  if (userId.value) userData.value = await fetchUser(userId.value);
});

// Cleanup: cancel stale requests (Vue 3.5+)
watch(searchQuery, async (query) => {
  const controller = new AbortController();
  onWatcherCleanup(() => controller.abort());
  const res = await fetch(`/api/search?q=${query}`, {
    signal: controller.signal,
  });
});

Gotcha: Watch reactive object properties with a getter:

watch(() => state.count, ...)

watch(state.count, ...)

See examples/vue-3-5-features.md for complete onWatcherCleanup patterns.

Pattern 4: Lifecycle and Cleanup

Always pair

onMounted

onUnmounted

const POLL_INTERVAL_MS = 5000;
let intervalId: ReturnType<typeof setInterval> | null = null;

onMounted(() => {
  intervalId = setInterval(fetchData, POLL_INTERVAL_MS);
});

onUnmounted(() => {
  if (intervalId) {
    clearInterval(intervalId);
    intervalId = null;
  }
});

See examples/lifecycle.md for WebSocket reconnection and event listener cleanup patterns.

Pattern 5: Composables

Extract reusable stateful logic into

use*

export function useCounter(options: UseCounterOptions = {}) {
  const { initialValue = 0, min = -Infinity, max = Infinity } = options;
  const count = ref(initialValue);
  const isAtMax = computed(() => count.value >= max);

  function increment() {
    if (count.value < max) count.value++;
  }
  function reset() {
    count.value = initialValue;
  }

  return { count, isAtMax, increment, reset }; // Return object with refs
}

Async composables should accept

MaybeRefOrGetter<T>

toValue()

{ data, error, isLoading }

See examples/composables.md for useFetch, useLocalStorage, useDebounce, and useIntersectionObserver implementations.

Pattern 6: defineModel for v-model (Vue 3.4+)

Replaces the

defineProps

defineEmits

<script setup lang="ts">
const model = defineModel<string>(); // Single v-model
const firstName = defineModel<string>("firstName"); // Named v-model
const [model, modifiers] = defineModel<string>({
  // With modifiers
  set(value) {
    return modifiers.capitalize
      ? value.charAt(0).toUpperCase() + value.slice(1)
      : value;
  },
});
</script>

See examples/vue-3-5-features.md for complete defineModel examples with named models and modifiers.

Pattern 7: Template Refs (Vue 3.5+)

useTemplateRef()

ref()

<script setup lang="ts">
const inputRef = useTemplateRef<HTMLInputElement>("myInput");
onMounted(() => inputRef.value?.focus());
</script>
<template>
  <input ref="myInput" type="text" />
</template>

For child component refs: Use

defineExpose()

ref<InstanceType<typeof Child>>()

See examples/define-expose.md for form validation with exposed methods and examples/vue-3-5-features.md for useTemplateRef in composables.

Pattern 8: useId for Accessible IDs (Vue 3.5+)

Generates SSR-safe unique IDs for form labels and ARIA attributes. Each call produces a different ID. Must be called in setup (not in computed).

<script setup lang="ts">
const id = useId();
</script>
<template>
  <label :for="id">Email</label>
  <input :id="id" type="email" />
</template>

See examples/vue-3-5-features.md for multi-field forms and ARIA patterns.

Pattern 9: Reactive Props Destructure (Vue 3.5+)

Destructured props are automatically reactive. Use JavaScript default syntax instead of

withDefaults()

watch()

<script setup lang="ts">
const {
  title,
  count = 0,
  items = () => [],
} = defineProps<{
  title: string;
  count?: number;
  items?: string[];
}>();

// CORRECT: getter wrapper
watch(
  () => count,
  (newCount) => {
    /* ... */
  },
);

// WRONG: passes value, not reactive source
// watch(count, ...) // Never triggers!
</script>

See examples/vue-3-5-features.md for complete reactive destructure examples.

Pattern 10: Provide/Inject

Type-safe dependency injection to avoid prop drilling. Define

InjectionKey<T>

// injection-keys.ts
export const THEME_KEY: InjectionKey<ThemeContext> = Symbol("theme");

// Provider: provide(THEME_KEY, { theme, toggleTheme });
// Consumer: const ctx = inject(THEME_KEY);
//           if (!ctx) throw new Error("Must be used within ThemeProvider");

See examples/provide-inject.md for a complete theme provider/consumer pattern.

Pattern 11: Async Components and Suspense

defineAsyncComponent

await

<script setup>

<Suspense>

onErrorCaptured

const LOADING_DELAY_MS = 200;
const LOAD_TIMEOUT_MS = 10000;

const HeavyChart = defineAsyncComponent({
  loader: () => import("@/components/HeavyChart.vue"),
  loadingComponent: LoadingSpinner,
  delay: LOADING_DELAY_MS,
  timeout: LOAD_TIMEOUT_MS,
});

See examples/async.md for Suspense boundaries with error handling.

Detailed Resources:

• examples/core.md - Complete component, template refs, focus management
• examples/reactivity.md - ref, reactive, computed patterns and anti-patterns
• examples/composables.md - useFetch, useLocalStorage, useDebounce, useIntersectionObserver
• examples/lifecycle.md - WebSocket, timers, event listeners, cleanup patterns
• examples/provide-inject.md - Theme provider, typed injection keys
• examples/define-expose.md - Form field validation, parent-child coordination
• examples/vue-3-5-features.md - defineModel, useTemplateRef, useId, onWatcherCleanup, reactive destructure, deferred Teleport
• examples/async.md - Lazy loading, Suspense, async setup
• reference.md - Decision frameworks, TypeScript patterns, anti-patterns, checklists

<red_flags>

RED FLAGS

High Priority Issues:

• Missing cleanup in

  onUnmounted

  - timers, listeners, subscriptions, WebSockets cause memory leaks
• Accessing

  ref.value

  in template - templates auto-unwrap refs, writing

  .value

  in templates is wrong
• Destructuring

  reactive()

  without

  toRefs()

  - loses reactivity silently
• Watching destructured prop directly -

  watch(count, ...)

  never triggers, use

  watch(() => count, ...)

Medium Priority Issues:

• Watch without async cleanup - causes race conditions; use

  onWatcherCleanup()

  (3.5+) or the cleanup callback
• Using

  provide()

  with string keys instead of typed

  InjectionKey<T>

  symbols - loses type safety
• Returning bare values from composables instead of an object with refs - breaks destructuring reactivity

Gotchas & Edge Cases:

• Refs in reactive objects are auto-unwrapped at root level, but NOT in arrays or Map/Set

• watchEffect

  runs immediately;

  watch

  is lazy by default
• Computed values are read-only by default; use getter/setter object for writable computed
• Top-level

  await

  makes a component async and requires

  <Suspense>

  in parent
• Provide values are not reactive by default - wrap in

  ref()

  or

  reactive()

  if consumers need reactivity

• onUnmounted

  won't run if component errors during setup - use error boundaries for critical cleanup

• useId()

  must not be called in computed - it generates a new ID each call

• defineModel

  returns a ref - use

  .value

  in script, auto-unwrapped in template

</red_flags>

<critical_reminders>

CRITICAL REMINDERS

All code must follow project conventions in CLAUDE.md

(You MUST use

<script setup>

(You MUST clean up all side effects (timers, listeners, subscriptions) in

onUnmounted

(You MUST use

ref()

reactive()

.value

(You MUST prefix all composable functions with

use

(You MUST wrap destructured props in a getter for

watch()

watch(() => count, ...)

watch(count, ...)

Failure to follow these rules will cause memory leaks, broken reactivity, and unmaintainable component APIs.

</critical_reminders>