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> syntax for all new Vue components)

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

(You MUST use ref() for primitives and reactive() for objects - access ref values via .value)

(You MUST prefix all composable functions with use following Vue conventions)

(You MUST wrap destructured props in a getter for watch() - watch(() => count, ...) not 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> are automatically available in the template. Use TypeScript generics with defineProps and defineEmits for type-safe interfaces.

<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() for primitives and reassignable values, reactive() for objects with nested properties. Access ref values via .value in script; templates unwrap automatically.

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() loses reactivity - use toRefs(state) if you need to destructure.

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() for explicit sources with access to old values. watchEffect() for automatic dependency tracking that runs immediately. Use onWatcherCleanup() (Vue 3.5+) to cancel stale async work.

// 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, ...) not watch(state.count, ...).

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

Pattern 4: Lifecycle and Cleanup

Always pair onMounted setup with onUnmounted cleanup. Timers, listeners, observers, WebSockets - anything opened must be closed.

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* functions. Return objects with refs (not bare values) so destructuring preserves reactivity.

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> inputs (use toValue() to normalize) and return { data, error, isLoading } refs.

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

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

Replaces the defineProps + defineEmits boilerplate for two-way binding. Returns a ref-like value that syncs with the parent.

<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() separates template refs from reactive refs. Use for dynamic ref names and in composables. Traditional ref() still works f