# Composition API de Vue 3: Guía completa para dominar la reactividad

> Aprende a utilizar la Composition API de Vue 3 con esta guía práctica. Domina ref, reactive, computed, watch y composables para construir aplicaciones Vue de alto rendimiento.

- Published: 2026-01-07
- Updated: 2026-04-06
- Author: SharpSkill
- Tags: vue 3, composition api, javascript, frontend, reactivity
- Reading time: 12 min

---

La Composition API de Vue 3 representa una evolución importante en la forma de estructurar componentes Vue. Este enfoque organiza el código por funcionalidad en lugar de por opciones, lo que facilita la reutilización de lógica y el mantenimiento de aplicaciones complejas.

> **Requisitos previos**
>
> Esta guía asume conocimientos básicos de Vue.js. Los ejemplos utilizan la sintaxis `<script setup>` introducida en Vue 3.2, que actualmente es el enfoque recomendado.

## Understanding Reactivity with ref and reactive

La reactividad es el pilar fundamental de Vue 3. Dos primitivas principales permiten crear datos reactivos: `ref` para valores primitivos y `reactive` para objetos complejos.

La función `ref` crea una referencia reactiva que envuelve un valor. Para acceder o modificar ese valor en el script, se debe utilizar la propiedad `.value`. En el template, Vue desenvuelve esta propiedad de forma automática.

```javascript
// Counter.vue
<script setup>
import { ref } from 'vue'

// Create a ref with initial value 0
const count = ref(0)

// Function that increments the counter
// Note: .value is required in the script
const increment = () => {
  count.value++
}

// Reset function
const reset = () => {
  count.value = 0
}
</script>

<template>
  <!-- In the template, no .value needed -->
  <div class="counter">
    <p>Counter: {{ count }}</p>
    <button @click="increment">+1</button>
    <button @click="reset">Reset</button>
  </div>
</template>
```

Para objetos con múltiples propiedades relacionadas, `reactive` ofrece una sintaxis más natural sin necesidad de `.value`.

```javascript
// UserProfile.vue
<script setup>
import { reactive } from 'vue'

// reactive for complex objects
// All properties are automatically reactive
const user = reactive({
  name: 'Jane Smith',
  email: 'jane@example.com',
  preferences: {
    theme: 'dark',
    notifications: true
  }
})

// Direct property modification (no .value)
const updateTheme = (newTheme) => {
  user.preferences.theme = newTheme
}

// Warning: do not reassign the entire object
// user = { ... } would break reactivity
</script>

<template>
  <div>
    <h2>{{ user.name }}</h2>
    <p>{{ user.email }}</p>
    <p>Theme: {{ user.preferences.theme }}</p>
  </div>
</template>
```

La regla general: utilizar `ref` para valores primitivos (string, number, boolean) y `reactive` para objetos estructurados.

## Computed Properties with computed

Las propiedades computadas derivan valores a partir del estado reactivo. Se almacenan en caché y solo se recalculan cuando cambian sus dependencias, lo que las hace altamente eficientes.

```javascript
// ProductList.vue
<script setup>
import { ref, computed } from 'vue'

// Product list
const products = ref([
  { id: 1, name: 'Laptop', price: 999, inStock: true },
  { id: 2, name: 'Mouse', price: 29, inStock: true },
  { id: 3, name: 'Keyboard', price: 79, inStock: false },
  { id: 4, name: 'Monitor', price: 299, inStock: true }
])

// Active filter
const showOnlyInStock = ref(false)

// computed: automatic filtering based on toggle
// Only recalculates if products or showOnlyInStock changes
const filteredProducts = computed(() => {
  if (showOnlyInStock.value) {
    return products.value.filter(p => p.inStock)
  }
  return products.value
})

// computed: total calculation with caching
const totalValue = computed(() => {
  return filteredProducts.value.reduce((sum, p) => sum + p.price, 0)
})

// computed: number of displayed items
const productCount = computed(() => filteredProducts.value.length)
</script>

<template>
  <div>
    <label>
      <input type="checkbox" v-model="showOnlyInStock" />
      Show only in-stock products
    </label>

    <p>{{ productCount }} products - Total: ${{ totalValue }}</p>

    <ul>
      <li v-for="product in filteredProducts" :key="product.id">
        {{ product.name }} - ${{ product.price }}
      </li>
    </ul>
  </div>
</template>
```

Las propiedades computadas también pueden ser de escritura mediante un getter y un setter, lo cual resulta útil para transformaciones bidireccionales.

```javascript
// FullName.vue
<script setup>
import { ref, computed } from 'vue'

const firstName = ref('John')
const lastName = ref('Doe')

// computed with getter AND setter
const fullName = computed({
  // Read: combine first and last name
  get() {
    return `${firstName.value} ${lastName.value}`
  },
  // Write: split the string into first/last name
  set(newValue) {
    const parts = newValue.split(' ')
    firstName.value = parts[0] || ''
    lastName.value = parts.slice(1).join(' ') || ''
  }
})
</script>

<template>
  <!-- Modifying fullName updates firstName and lastName -->
  <input v-model="fullName" placeholder="Full name" />
  <p>First name: {{ firstName }}</p>
  <p>Last name: {{ lastName }}</p>
</template>
```

## Watchers with watch and watchEffect

Los watchers ejecutan efectos secundarios en respuesta a cambios en los datos. Vue 3 ofrece dos enfoques: `watch` para un control preciso y `watchEffect` para un seguimiento automático.

> **When to use watch vs watchEffect?**
>
> `watch` ofrece control preciso sobre las dependencias y proporciona tanto el valor anterior como el nuevo. `watchEffect` resulta más simple cuando todas las dependencias reactivas utilizadas deben disparar el efecto.

```javascript
// SearchComponent.vue
<script setup>
import { ref, watch, watchEffect } from 'vue'

const searchQuery = ref('')
const searchResults = ref([])
const isLoading = ref(false)

// watch: observes a specific source
// Provides oldValue and newValue, allows debouncing
watch(searchQuery, async (newQuery, oldQuery) => {
  console.log(`Search changed from "${oldQuery}" to "${newQuery}"`)

  // Don't search if less than 3 characters
  if (newQuery.length < 3) {
    searchResults.value = []
    return
  }

  isLoading.value = true

  try {
    // Simulated API call
    const response = await fetch(`/api/search?q=${newQuery}`)
    searchResults.value = await response.json()
  } finally {
    isLoading.value = false
  }
}, {
  // Watcher options
  debounce: 300, // Wait 300ms after last keystroke
  immediate: false // Don't execute immediately
})

// watchEffect: automatic dependency tracking
// Runs immediately and on every change
watchEffect(() => {
  // All refs used here are automatically tracked
  console.log(`Current state: ${searchResults.value.length} results`)
  console.log(`Loading: ${isLoading.value}`)
})
</script>

<template>
  <div>
    <input v-model="searchQuery" placeholder="Search..." />
    <p v-if="isLoading">Loading...</p>
    <ul v-else>
      <li v-for="result in searchResults" :key="result.id">
        {{ result.title }}
      </li>
    </ul>
  </div>
</template>
```

Para observar objetos anidados o arreglos, la opción `deep` es necesaria con `watch`.

```javascript
// DeepWatch.vue
<script setup>
import { reactive, watch } from 'vue'

const settings = reactive({
  display: {
    theme: 'light',
    fontSize: 14
  },
  notifications: {
    email: true,
    push: false
  }
})

// deep: true to observe nested changes
watch(
  () => settings.display,
  (newDisplay) => {
    console.log('Display settings changed:', newDisplay)
    // Save to localStorage for example
    localStorage.setItem('display', JSON.stringify(newDisplay))
  },
  { deep: true }
)
</script>
```

## Creating Reusable Composables

Los composables son funciones que encapsulan lógica reactiva reutilizable. Este enfoque es una de las grandes fortalezas de la Composition API para compartir código entre componentes.

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

// Composable for HTTP requests
// Automatically handles loading, errors, and refetching
export function useFetch(url) {
  const data = ref(null)
  const error = ref(null)
  const isLoading = ref(false)

  // Reusable fetch function
  async function fetchData() {
    isLoading.value = true
    error.value = null

    try {
      // toValue() allows accepting a ref or a value
      const response = await fetch(toValue(url))

      if (!response.ok) {
        throw new Error(`HTTP ${response.status}`)
      }

      data.value = await response.json()
    } catch (e) {
      error.value = e.message
    } finally {
      isLoading.value = false
    }
  }

  // watchEffect for automatic refetch if url is a ref
  watchEffect(() => {
    fetchData()
  })

  // Expose state and methods
  return {
    data,
    error,
    isLoading,
    refetch: fetchData
  }
}
```

Este composable puede utilizarse de forma declarativa en cualquier componente.

```javascript
// UserList.vue
<script setup>
import { useFetch } from '@/composables/useFetch'

// Simple composable usage
const { data: users, isLoading, error, refetch } = useFetch('/api/users')
</script>

<template>
  <div>
    <button @click="refetch" :disabled="isLoading">
      Refresh
    </button>

    <p v-if="isLoading">Loading users...</p>
    <p v-else-if="error" class="error">Error: {{ error }}</p>

    <ul v-else-if="users">
      <li v-for="user in users" :key="user.id">
        {{ user.name }}
      </li>
    </ul>
  </div>
</template>
```

A continuación, otro ejemplo de composable para gestionar el estado de un formulario con validación.

```javascript
// composables/useForm.js
import { reactive, computed } from 'vue'

// Form management composable
export function useForm(initialValues, validationRules) {
  // Form state
  const form = reactive({
    values: { ...initialValues },
    errors: {},
    touched: {}
  })

  // Validate a specific field
  const validateField = (field) => {
    const rules = validationRules[field]
    if (!rules) return true

    for (const rule of rules) {
      const result = rule(form.values[field])
      if (result !== true) {
        form.errors[field] = result
        return false
      }
    }

    form.errors[field] = null
    return true
  }

  // Validate entire form
  const validate = () => {
    let isValid = true
    for (const field in validationRules) {
      if (!validateField(field)) {
        isValid = false
      }
    }
    return isValid
  }

  // computed: form is valid if no errors
  const isValid = computed(() => {
    return Object.values(form.errors).every(e => !e)
  })

  // Mark a field as touched (to display errors)
  const touch = (field) => {
    form.touched[field] = true
    validateField(field)
  }

  // Reset the form
  const reset = () => {
    form.values = { ...initialValues }
    form.errors = {}
    form.touched = {}
  }

  return {
    form,
    isValid,
    validate,
    validateField,
    touch,
    reset
  }
}
```

## Lifecycle Hook Management

La Composition API proporciona hooks de ciclo de vida como funciones que se invocan dentro de setup. Estos hooks permiten ejecutar código en momentos específicos del ciclo de vida del componente.

> **Important Cleanup**
>
> Siempre se deben limpiar los efectos secundarios (timers, listeners de eventos, suscripciones) en `onUnmounted` para evitar fugas de memoria.

```javascript
// LifecycleDemo.vue
<script setup>
import {
  ref,
  onMounted,
  onUnmounted,
  onBeforeUpdate,
  onUpdated
} from 'vue'

const windowWidth = ref(window.innerWidth)
const updateCount = ref(0)

// Handler for resize
const handleResize = () => {
  windowWidth.value = window.innerWidth
}

// onMounted: component inserted into DOM
// Ideal for initial API calls and event listeners
onMounted(() => {
  console.log('Component mounted')
  window.addEventListener('resize', handleResize)

  // Example: initialize a third-party library
  // chart = new Chart(chartRef.value, config)
})

// onUnmounted: component removed from DOM
// CRITICAL: clean up all side effects
onUnmounted(() => {
  console.log('Component unmounted')
  window.removeEventListener('resize', handleResize)

  // Clean up subscriptions, timers, etc.
  // chart?.destroy()
})

// onBeforeUpdate: before DOM update
onBeforeUpdate(() => {
  console.log('Before update')
})

// onUpdated: after DOM update
onUpdated(() => {
  updateCount.value++
  console.log(`DOM updated (${updateCount.value} times)`)
})
</script>

<template>
  <div>
    <p>Window width: {{ windowWidth }}px</p>
    <p>DOM updates: {{ updateCount }}</p>
  </div>
</template>
```

## Template Refs and DOM Access

Los template refs proporcionan acceso directo a elementos del DOM o instancias de componentes hijos. Esto sigue siendo útil en casos donde la manipulación directa es necesaria.

```javascript
// InputFocus.vue
<script setup>
import { ref, onMounted } from 'vue'

// ref for the DOM element
// Same name as the ref attribute in the template
const inputRef = ref(null)

// Function to focus the input
const focusInput = () => {
  // Access to the native DOM element
  inputRef.value?.focus()
}

// Auto-focus on mount
onMounted(() => {
  focusInput()
})

// Expose the method to parent if needed
defineExpose({
  focus: focusInput
})
</script>

<template>
  <div>
    <!-- The ref attribute binds the element to inputRef -->
    <input ref="inputRef" type="text" placeholder="Auto-focused" />
    <button @click="focusInput">Refocus</button>
  </div>
</template>
```

## Parent-Child Communication with Props and Emits

La Composition API moderniza la declaración de props y eventos con `defineProps` y `defineEmits`, ofreciendo una mejor integración con TypeScript.

```javascript
// ChildComponent.vue
<script setup>
// defineProps: declares expected props
// With default values via withDefaults
const props = withDefaults(defineProps<{
  title: string
  count?: number
  items?: string[]
}>(), {
  count: 0,
  items: () => []
})

// defineEmits: declares emitted events
// Precise payload typing
const emit = defineEmits<{
  (e: 'update', value: number): void
  (e: 'submit', data: { title: string; items: string[] }): void
}>()

// Function that emits an event
const handleSubmit = () => {
  emit('submit', {
    title: props.title,
    items: props.items
  })
}

const increment = () => {
  emit('update', props.count + 1)
}
</script>

<template>
  <div class="card">
    <h3>{{ title }}</h3>
    <p>Count: {{ count }}</p>
    <button @click="increment">Increment</button>
    <button @click="handleSubmit">Submit</button>
  </div>
</template>
```

```javascript
// ParentComponent.vue
<script setup>
import { ref } from 'vue'
import ChildComponent from './ChildComponent.vue'

const currentCount = ref(0)
const items = ref(['Item 1', 'Item 2'])

// Handler for update event
const onUpdate = (newValue) => {
  currentCount.value = newValue
}

// Handler for submit event
const onSubmit = (data) => {
  console.log('Data submitted:', data)
}
</script>

<template>
  <ChildComponent
    title="My Component"
    :count="currentCount"
    :items="items"
    @update="onUpdate"
    @submit="onSubmit"
  />
</template>
```

## Provide and Inject for Dependency Injection

Para compartir datos entre componentes distantes sin necesidad de pasar props a través de cada nivel, Vue 3 ofrece `provide` e `inject`.

```javascript
// App.vue (or an ancestor component)
<script setup>
import { provide, ref, readonly } from 'vue'

// Global theme state
const theme = ref('light')

// Function to toggle theme
const toggleTheme = () => {
  theme.value = theme.value === 'light' ? 'dark' : 'light'
}

// provide: makes available to descendants
// readonly prevents direct modification by children
provide('theme', readonly(theme))
provide('toggleTheme', toggleTheme)
</script>

<template>
  <div :class="theme">
    <slot />
  </div>
</template>
```

```javascript
// DeepNestedComponent.vue (anywhere in the tree)
<script setup>
import { inject } from 'vue'

// inject: retrieves value provided by an ancestor
// Default value if not found
const theme = inject('theme', 'light')
const toggleTheme = inject('toggleTheme', () => {})
</script>

<template>
  <div>
    <p>Current theme: {{ theme }}</p>
    <button @click="toggleTheme">
      Switch to {{ theme === 'light' ? 'dark' : 'light' }}
    </button>
  </div>
</template>
```

## Conclusion

La Composition API de Vue 3 ofrece un enfoque potente y flexible para organizar el código de aplicaciones Vue. Conceptos clave a recordar:

- **ref** para valores primitivos, **reactive** para objetos complejos
- **computed** para valores derivados con caché automático
- **watch** y **watchEffect** para efectos secundarios reactivos
- **Composables** para extraer y reutilizar lógica entre componentes
- **Hooks de ciclo de vida funcionales** (`onMounted`, `onUnmounted`, etc.)
- **provide/inject** para inyección de dependencias sin prop drilling

Este enfoque facilita la creación de aplicaciones mantenibles y testeables, al mismo tiempo que ofrece una excelente integración con TypeScript. El siguiente paso consiste en explorar patrones avanzados como composables asíncronos y la integración con Pinia para la gestión de estado global.

---

Source: SharpSkill (https://sharpskill.dev), tech interview preparation for your real stack.
HTML version of this page: https://sharpskill.dev/es/blog/vue-nuxt/vue-3-composition-api-complete-guide