Skip to content

Vue 3 Hoja de referencia

Framework de JavaScript progresivo para construir interfaces de usuario.

01

Primeros pasos

Hello World y comentarios

Una app de Vue 3 empieza con createApp() y mount() sobre un elemento del DOM. La interpolación usa llaves dobles {{ }} para renderizar datos reactivos. Los comentarios HTML aparecen en el DOM renderizado; para comentarios que no se filtren, usa /* */ dentro de los bloques <script>.

vue3
<!-- index.html -->
<div id="app">
  <p>{{ message }}</p>
  <!-- This is an HTML comment, visible in DOM -->
</div>

<script type="module">
  import { createApp } from 'vue'

  createApp({
    data() {
      return { message: 'Hello Vue 3!' }
    }
  }).mount('#app')
</script>

Estructura de SFC (Single File Component)

Un SFC agrupa plantilla, script y estilo en un solo archivo .vue. <script setup> es la sintaxis recomendada para la Composition API — concisa y con cero boilerplate. Los estilos scoped solo aplican al componente actual, evitando fugas. Cada SFC compila a un módulo de JavaScript.

vue3
<template>
  <button @click="count++">Count: {{ count }}</button>
</template>

<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>

<style scoped>
button { color: #42B883; }
</style>

Instancia de app y mount

createApp devuelve una instancia de aplicación acotada a sí misma — sin estado Vue global, así que puedes montar varias apps independientes en una página. Registra plugins, aporta valores globales y fija la configuración antes de llamar a mount(). Tras el mount, los cambios de configuración posteriores no surten efecto.

vue3
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

// global config / plugins before mounting
app.config.errorHandler = (err) => console.error(err)
app.provide('apiKey', '12345')

app.mount('#app')

Andamiaje del proyecto (Vite)

npm create vue@latest es la herramienta oficial de andamiaje, ofreciendo configuración opcional de TypeScript, Router, Pinia y Vitest. Usa Vite para un arranque instantáneo del servidor de desarrollo y HMR. create-vite es la herramienta de más bajo nivel si quieres una plantilla mínima sin las opiniones de Vue.

vue3
# scaffold a new Vue project with Vite
npm create vue@latest my-app
cd my-app
npm install
npm run dev       # start dev server (HMR)
npm run build     # production build to /dist

# or with create-vite directly
npm create vite@latest my-app -- --template vue-ts

defineOptions y defineProps

defineProps, defineEmits y defineOptions son macros en tiempo de compilación — no hace falta importarlas. defineProps declara el contrato de props del componente con validación en runtime. defineOptions te deja fijar name, inheritAttrs y otras opciones que no son expresables en <script setup> directamente.

vue3
<script setup>
// declare props with types and defaults
const props = defineProps({
  title: String,
  count: { type: Number, default: 0 }
})

// declare emits
const emit = defineEmits(['update', 'delete'])

// additional non-reactive options
defineOptions({ name: 'MyButton', inheritAttrs: false })
</script>
02

Sintaxis de plantillas

Interpolación de texto

{{ }} renderiza texto de forma segura (con escape HTML). v-once congela un binding tras el primer render para contenido estático. v-html inyecta HTML crudo — úsalo solo en contenido confiable para evitar XSS. Dentro de {{ }} puedes usar cualquier expresión simple de JavaScript, pero no sentencias como asignaciones o declaraciones var.

vue3
<template>
  <p>{{ message }}</p>
  <!-- renders the value of message -->

  <!-- one-time binding (no updates after render) -->
  <span v-once>{{ initialCount }}</span>

  <!-- raw HTML (sanitize to avoid XSS!) -->
  <div v-html="rawHtmlContent"></div>

  <!-- expressions are supported -->
  <p>{{ count * 2 }}</p>
  <p>{{ isReady ? 'Yes' : 'No' }}</p>
  <p>{{ message.split('').reverse().join('') }}</p>
</template>

Binding de atributos

v-bind (abreviatura :) enlaza atributos de forma reactiva. Para class puedes pasar un objeto (las claves verdaderas se aplican), un array o una cadena. style acepta un objeto con claves en camelCase o kebab-case. La sintaxis de argumento dinámico :[expr] permite que el propio nombre del atributo sea reactivo — útil para nombres de eventos o atributos localizados.

vue3
<template>
  <!-- bind an attribute -->
  <img v-bind:src="imageUrl" />
  <img :src="imageUrl" />  <!-- shorthand -->

  <!-- bind class -->
  <div :class="{ active: isActive, error: hasError }"></div>
  <div :class="['btn', isActive && 'active']"></div>

  <!-- bind style -->
  <div :style="{ color: textColor, fontSize: size + 'px' }"></div>

  <!-- dynamic attribute name -->
  <button :[eventName]="handler">Click</button>
</template>

Atributos booleanos y multivalor

Para atributos booleanos como disabled o checked, Vue renderiza el atributo solo cuando el valor es verdadero. class y style son especiales: Vue fusiona los valores estáticos y enlazados en lugar de reemplazarlos. Para inputs de formulario, prefiere v-model a enlazar manualmente :value y @input.

vue3
<template>
  <!-- boolean attribute: presence depends on value -->
  <input :disabled="isDisabled" />
  <button :disabled="!canSubmit">Submit</button>

  <!-- class merging: bound class merges with static class -->
  <div class="card" :class="{ highlighted: isFeatured }"></div>

  <!-- style merging: bound style merges with static style -->
  <div style="color: red" :style="{ fontSize: '14px' }"></div>

  <!-- form attributes: value is bound with v-model instead -->
  <input v-model="text" />
</template>

Modificadores y expresiones

Los modificadores son postfijos señalados con un punto, indicando manejo especial. Los modificadores de evento (.prevent, .stop, .once, .self) envuelven el manejador con la función correspondiente del DOM. Los de tecla (.enter, .esc, .ctrl) filtran eventos por tecla. Los de v-model (.trim, .number, .lazy) transforman el valor de entrada antes de asignar.

vue3
<template>
  <!-- .prevent calls event.preventDefault() -->
  <form @submit.prevent="onSubmit">...</form>

  <!-- .stop calls event.stopPropagation() -->
  <button @click.stop="doStuff">Click</button>

  <!-- .once runs handler only one time -->
  <button @click.once="init">Init</button>

  <!-- .trim and .lazy modifiers on v-model -->
  <input v-model.trim="email" />
  <input v-model.lazy="text" />

  <!-- chain multiple modifiers -->
  <input @keyup.enter.ctrl="onCombo" />
</template>

Refs de plantilla

Las template refs dan acceso directo a elementos del DOM. Declara un ref() con el mismo nombre que el atributo ref — Vue asigna el nodo del DOM tras el montaje. Accede dentro de onMounted (o después); antes del montaje, la ref es null. Para v-for, la ref se convierte en un array de elementos. Evita recurrir a refs cuando bastarían los flujos de datos reactivos.

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

// declare a ref matching the template ref attribute
const inputEl = ref(null)

onMounted(() => {
  // access the DOM node after mount
  inputEl.value.focus()
})
</script>

<template>
  <input ref="inputEl" />
</template>
03

Directivas

v-if / v-else-if / v-else

v-if renderiza elementos condicionalmente — se añaden/quitan del DOM. v-else-if y v-else se encadenan con un v-if precedente. Envuelve varios elementos en un <template v-if> cuando no quieras un elemento envolvente extra. v-if tiene mayor coste de alternancia (creación del DOM) pero menor coste inicial que v-show cuando la condición es falsa.

vue3
<template>
  <div v-if="type === 'A'">Type A</div>
  <div v-else-if="type === 'B'">Type B</div>
  <div v-else-if="type === 'C'">Type C</div>
  <div v-else>Unknown type</div>

  <!-- use <template> for invisible wrapper -->
  <template v-if="showHeader">
    <h1>Title</h1>
    <p>Subtitle</p>
  </template>
</template>

v-show vs v-if

Usa v-if cuando la condición cambie rara vez — los elementos se destruyen y recrean, ahorrando coste de render cuando están ocultos. Usa v-show para elementos alternados con frecuencia (pestañas, desplegables) — el elemento permanece en el DOM y solo display:none se alterna, así que alternar es barato. v-show no funciona con <template> ni v-else.

vue3
<template>
  <!-- v-if removes from DOM when false -->
  <p v-if="isVisible">I'm created/destroyed</p>

  <!-- v-show just toggles display:none -->
  <p v-show="isVisible">I'm always in DOM, just hidden</p>
</template>

<script setup>
import { ref } from 'vue'
const isVisible = ref(true)
</script>

v-for y :key

v-for itera arrays, objetos o un rango de números. El atributo :key es OBLIGATORIO para la identidad track-by — deja a Vue reutilizar nodos del DOM eficientemente durante el reordenamiento. Usa un id único estable como clave; nunca uses el índice del array (se rompe cuando los ítems se mueven). v-for tiene mayor prioridad que v-if en el mismo elemento — evita usar ambos en un elemento.

vue3
<template>
  <!-- iterate over array -->
  <li v-for="item in items" :key="item.id">
    {{ item.name }}
  </li>

  <!-- iterate with index -->
  <li v-for="(item, index) in items" :key="item.id">
    {{ index }}: {{ item.name }}
  </li>

  <!-- iterate over object -->
  <li v-for="(value, key) in user" :key="key">
    {{ key }}: {{ value }}
  </li>

  <!-- range (1 to n) -->
  <span v-for="n in 10" :key="n">{{ n }}</span>
</template>

Bindings v-model

v-model es el binding bidireccional para inputs de formulario: sincroniza el valor del input con el estado reactivo. Un checkbox único se enlaza a un booleano; varios checkboxes con el mismo v-model se enlazan a un array de valores marcados. Usa modificadores: .lazy (sincroniza en change en lugar de input), .number (castea a número), .trim (recorta espacios).

vue3
<template>
  <!-- text input -->
  <input v-model="text" />

  <!-- multi-line textarea -->
  <textarea v-model="message"></textarea>

  <!-- checkbox (single = boolean, multiple = array) -->
  <input type="checkbox" v-model="isChecked" />
  <input type="checkbox" value="apple" v-model="fruits" />
  <input type="checkbox" value="banana" v-model="fruits" />

  <!-- radio -->
  <input type="radio" value="A" v-model="picked" />

  <!-- select -->
  <select v-model="selected">
    <option value="a">A</option>
    <option value="b">B</option>
  </select>
</template>

Directivas personalizadas

Las directivas personalizadas te permiten manipular directamente elementos del DOM. En <script setup>, cualquier variable llamada vAlgo (camelCase) está disponible automáticamente como v-algo en la plantilla. El objeto de directiva tiene hooks de ciclo de vida: mounted, updated, unmounted, etc. Prefiere componentes a directivas cuando necesites reactividad — las directivas son para trabajo de DOM de bajo nivel como focus, tooltips o arrastre.

vue3
<script setup>
// local directive: function form (mounted + updated)
const vFocus = {
  mounted: (el) => el.focus()
}

// global registration
// app.directive('focus', { mounted: el => el.focus() })
</script>

<template>
  <input v-focus />
</template>
04

Propiedades computadas

Computed básico

computed crea un getter cacheado que solo se reevalúa cuando cambian sus dependencias. A diferencia de una llamada a función, el acceso repetido devuelve el valor cacheado hasta que una dependencia se actualiza. En <script>, accede vía .value; en plantillas, Vue auto-desenvuelve. Usa computed en lugar de funciones siempre que el valor dependa de estado reactivo — es más rápido y declarativo.

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

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

// computed caches based on dependencies
const fullName = computed(() => {
  return firstName.value + ' ' + lastName.value
})

// access via .value in script
console.log(fullName.value)  // 'John Doe'
</script>

<template>
  <!-- use without .value in template -->
  <p>{{ fullName }}</p>
</template>

Computed escribible

Por defecto computed es de solo lectura, pero puedes proporcionar getter y setter. El setter se invoca cuando asignas a .value. Útil para binding bidireccional sobre estado derivado, por ejemplo sincronizar un input de nombre completo de vuelta a los campos de nombre/apellido. Cuidado de evitar bucles infinitos — los setters no deberían fijar directamente las propias dependencias del computed de forma que se re-dispare a sí mismo.

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

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

const fullName = computed({
  get() {
    return firstName.value + ' ' + lastName.value
  },
  set(newValue) {
    [firstName.value, lastName.value] = newValue.split(' ')
  }
})

// assignment triggers the setter
fullName.value = 'Jane Smith'
</script>

Computed vs funciones

Las propiedades computadas cachean su resultado según las dependencias — solo se vuelven a correr cuando items cambia. Las funciones se vuelven a correr en cada render sin importar qué cambió. Usa computed para valores derivados del estado reactivo; usa funciones para acciones que toman parámetros o tienen efectos secundarios. Computed también aclara la intención: 'este valor se deriva' frente a 'haz esta cosa'.

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

const items = ref([1, 2, 3, 4, 5])

// computed: cached, re-runs only if items changes
const doubled = computed(() =>
  items.value.map(x => x * 2)
)

// method: re-runs on every render
function getDoubled() {
  return items.value.map(x => x * 2)
}
</script>

<template>
  <!-- cached, no recompute on unrelated re-renders -->
  <p>{{ doubled }}</p>

  <!-- re-invoked on every render -->
  <p>{{ getDoubled() }}</p>
</template>

Trampas del getter de computed

Los getters de computed deben ser puros: sin efectos secundarios (sin mutaciones, sin async, sin peticiones). No llames a Date.now() ni Math.random() — no son reactivos así que el computed no se actualizará. Si necesitas un efecto secundario, usa un watcher. Si necesitas async, computed no espera — usa watch + una ref, o async setup con Suspense.

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

const date = ref(new Date())

// BAD: non-reactive Date.now() — won't update
const badTime = computed(() => Date.now())

// BAD: side effect inside computed
const count = ref(0)
const bad = computed(() => {
  count.value++   // never mutate state in computed!
  return count.value
})

// GOOD: pure function of reactive state
const formatted = computed(() =>
  date.value.toLocaleDateString()
)
</script>

Computed en la Options API

En la Options API, declara computed en la opción computed. Se acceden como this.total (sin .value, sin paréntesis) — Vue auto-desenvuelve. El computed escribible usa funciones get/set. Las propiedades computadas se exponen en la instancia del componente junto a data y methods, todas accesibles vía this.

vue3
<script>
export default {
  data() {
    return { price: 100, quantity: 2 }
  },
  computed: {
    total() {
      return this.price * this.quantity
    },
    discounted: {
      get() { return this.total * 0.9 },
      set(v) { this.price = v / 0.9 / this.quantity }
    }
  },
  methods: {
    checkout() { console.log(this.total) }
  }
}
</script>
05

Watchers

watch básico

watch corre un callback cuando la fuente observada cambia. La fuente puede ser una ref, una propiedad de un objeto reactivo (vía getter) o un array de fuentes. El callback recibe (valorNuevo, valorAntiguo). Usa un getter () => x.y para observar propiedades reactivas anidadas. Los watchers son para efectos secundarios (fetch, log, persistir) — no para derivar estado (para eso usa computed).

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

const question = ref('')

// watch a ref
watch(question, (newValue, oldValue) => {
  console.log('changed from', oldValue, 'to', newValue)
})

// watch a getter (computed source)
watch(
  () => question.value.length,
  (newLen) => {
    if (newLen > 100) console.warn('Too long!')
  }
)
</script>

Watch profundo e immediate

deep: true hace que watch se dispare ante cambios en cualquier propiedad anidada de un objeto — útil pero caro en estructuras grandes. immediate: true dispara el callback de inmediato en el setup (oldValue es undefined en la primera llamada). Evita el watch profundo sobre objetos enormes — prefiere observar un getter concreto () => obj.campoEspecifico por mejor rendimiento.

vue3
<script setup>
import { reactive, watch } from 'vue'

const user = reactive({
  name: 'Alice',
  address: { city: 'NYC', zip: '10001' }
})

// deep: watch nested property changes
watch(
  () => user.address,
  (newAddr) => console.log('address changed', newAddr),
  { deep: true }
)

// immediate: run callback right away
watch(
  user,
  (val) => saveToServer(val),
  { deep: true, immediate: true }
)
</script>

watchEffect (rastreo automático)

watchEffect corre el callback de inmediato y rastrea automáticamente cualquier dependencia reactiva accedida dentro. Cada vez que cualquier dependencia rastreada cambia, el callback vuelve a correr. A diferencia de watch, no especificas fuente — se infiere. Usa watchEffect cuando no necesites el oldValue y quieras rastreo automático de dependencias. Útil para configurar suscripciones que leen varias fuentes reactivas.

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

const a = ref(1)
const b = ref(2)

// runs immediately and tracks dependencies automatically
watchEffect(() => {
  console.log('a + b =', a.value + b.value)
})
// logs: a + b = 3

a.value = 10  // logs: a + b = 12

// stop the watcher
const stop = watchEffect(() => { /* ... */ })
stop()  // cleanup
</script>

watch vs watchEffect

Elige watch cuando necesites: oldValue, ejecución perezosa (saltarte la corrida inicial) u observar una fuente concreta explícitamente. Elige watchEffect cuando: quieras ejecución inmediata, no necesites oldValue, o tengas efectos secundarios que toquen varios valores reactivos y quieras rastreo automático. watch con una fuente de array te da arrays de valores nuevos/antiguos en el callback.

vue3
<script setup>
import { ref, watch, watchEffect } from 'vue'

const count = ref(0)

// watch: lazy, explicit source, has oldValue
watch(count, (newVal, oldVal) => {
  console.log('count changed:', oldVal, '->', newVal)
})

// watchEffect: eager, auto-tracked, no oldValue
watchEffect(() => {
  console.log('count is', count.value)
})
// logs immediately: count is 0

// watch multiple sources
const a = ref(1), b = ref(2)
watch([a, b], ([newA, newB], [oldA, oldB]) => {
  console.log('a or b changed')
})
</script>

Limpieza y flush del watcher

El callback onCleanup (tercer argumento) registra una función de limpieza que corre antes de la siguiente invocación del watcher — perfecto para cancelar peticiones en curso, limpiar temporizadores o desuscribirse. flush: 'post' corre el watcher tras actualizarse el DOM de Vue (útil cuando necesitas leer el DOM actualizado). 'sync' corre sincrónicamente al cambiar la dependencia — rara vez necesario y puede causar problemas de rendimiento.

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

const id = ref(1)

// cleanup function: runs before next callback
watch(id, (newId, oldId, onCleanup) => {
  const controller = new AbortController()
  fetch(`/api/user/${newId}`, { signal: controller.signal })
    .then(r => r.json())

  // cancel previous request when id changes again
  onCleanup(() => controller.abort())
}, { flush: 'post' })

// flush: 'pre' (default) | 'post' (after DOM update) | 'sync'
</script>
06

Renderizado condicional

v-if vs v-show

v-if realmente añade/quita elementos del DOM — mayor coste inicial pero coste cero cuando está oculto. v-show siempre renderiza el elemento y alterna display:none — alternar es más barato pero el elemento existe incluso oculto. Usa v-if para condicionales que cambian rara vez (o cuando los elementos ocultos no deberían existir en absoluto). Usa v-show para UI alternada con frecuencia como pestañas, desplegables, modals.

vue3
<template>
  <!-- v-if: element removed from DOM when false -->
  <div v-if="isLoggedIn">Welcome back</div>

  <!-- v-show: element stays, display toggles -->
  <div v-show="isLoggedIn">Welcome back</div>
</template>

<!-- v-show compiles to: -->
<!-- <div style="display: none;">Welcome back</div> when false -->

<!-- v-if does not render the element at all when false -->

Cadena v-if con v-else

v-else-if y v-else deben seguir inmediatamente a un elemento v-if (u otro v-else-if) — ningún otro elemento puede interponerse. La cadena evalúa de arriba abajo y se detiene en la primera condición verdadera. El v-else final atrapa cualquier caso restante. Este patrón es genial para UI basada en estado (cargando, error, vacío, éxito).

vue3
<template>
  <div v-if="status === 'loading'">Loading...</div>
  <div v-else-if="status === 'error'">Error occurred</div>
  <div v-else-if="status === 'empty'">No items</div>
  <div v-else>
    <ul>
      <li v-for="item in items" :key="item.id">{{ item.name }}</li>
    </ul>
  </div>
</template>

Envoltorio <template> para v-if

<template> es un envoltorio lógico que no se renderiza al DOM — perfecto para agrupar varios elementos bajo un v-if o v-for sin añadir HTML extra. Esto mantiene tu marcado semántico (sin divs sueltos). Para v-for sobre template, aún necesitas :key sobre el propio elemento template.

vue3
<template>
  <!-- group elements under one condition, no wrapper div -->
  <template v-if="showProfile">
    <h2>{{ user.name }}</h2>
    <p>{{ user.bio }}</p>
    <button @click="edit">Edit</button>
  </template>

  <!-- combine v-if with v-for on template -->
  <template v-for="item in items" :key="item.id">
    <dt>{{ item.term }}</dt>
    <dd>{{ item.def }}</dd>
  </template>
</template>

Prioridad v-if vs v-for

Nunca uses v-if y v-for en el mismo elemento. En Vue 3, v-if tiene mayor prioridad, así que corre antes que v-for — la variable del bucle aún no está disponible, causando errores. En su lugar, filtra el array con una propiedad computada (preferido) o un .filter() en línea. Usa un <template v-for> envolvente con un v-if interior si lo necesitas.

vue3
<template>
  <!-- AVOID: v-if and v-for on same element -->
  <!-- In Vue 3, v-if has higher priority than v-for -->
  <!-- so 'item' is not defined when v-if evaluates -->
  <li v-for="item in items" v-if="item.active" :key="item.id">
    {{ item.name }}
  </li>

  <!-- GOOD: filter first, then iterate -->
  <li
    v-for="item in items.filter(i => i.active)"
    :key="item.id"
  >
    {{ item.name }}
  </li>

  <!-- BEST: use computed for the filtered list -->
</template>

Transition con v-if

Envuelve un elemento v-if (o v-show) en <Transition> para animar entrada/salida. Vue añade clases en los momentos correctos: v-enter-from, v-enter-active, v-enter-to (y v-leave-*). Define transiciones CSS sobre estas clases. name='fade' reemplaza el prefijo 'v-' por 'fade-'. Transition solo soporta un único elemento hijo — usa TransitionGroup para listas.

vue3
<template>
  <Transition name="fade">
    <p v-if="show">Hello</p>
  </Transition>
</template>

<style>
.fade-enter-active, .fade-leave-active {
  transition: opacity 0.3s;
}
.fade-enter-from, .fade-leave-to {
  opacity: 0;
}
</style>
07

Renderizado de listas

v-for con arrays

v-for itera arrays, exponiendo cada ítem y (opcionalmente) el índice. Enlaza SIEMPRE :key a un valor único estable como item.id — esto deja a Vue emparejar nodos antiguos y nuevos durante el reordenamiento, preservando el estado de componentes y el DOM eficientemente. Usar el índice como clave se rompe cuando se insertan/quitan/reordenan ítems, causando bugs sutiles.

vue3
<script setup>
import { ref } from 'vue'
const items = ref([
  { id: 1, name: 'Apple' },
  { id: 2, name: 'Banana' },
  { id: 3, name: 'Cherry' }
])
</script>

<template>
  <!-- always provide :key with stable unique id -->
  <li v-for="item in items" :key="item.id">
    {{ item.name }}
  </li>

  <!-- with index (avoid as :key) -->
  <li v-for="(item, index) in items" :key="item.id">
    {{ index + 1 }}. {{ item.name }}
  </li>
</template>

v-for con objetos y rango

v-for sobre un objeto itera valores por defecto; el segundo argumento es la clave, el tercero el índice. El orden de iteración de objetos sigue a Object.keys() (orden de inserción para claves de cadena). v-for con un número n itera de 1 a n (inclusivo, no de 0 a n-1). Para listas filtradas u ordenadas, prefiere una propiedad computada sobre la lógica en línea por legibilidad y caché.

vue3
<template>
  <!-- iterate object: (value, key, index) -->
  <div v-for="(value, key, index) in user" :key="key">
    {{ index }}. {{ key }}: {{ value }}
  </div>

  <!-- iterate a number range (1 to n inclusive) -->
  <span v-for="n in 10" :key="n">{{ n }} </span>
  <!-- 1 2 3 4 5 6 7 8 9 10 -->

  <!-- use v-for of computed for derived lists -->
  <li v-for="todo in doneTodos" :key="todo.id">
    {{ todo.text }}
  </li>
</template>

Detección de cambios en listas

Vue 3 usa reactividad basada en Proxy, así que mutar arrays con push, pop, splice, sort, reverse dispara actualizaciones — sin advertencias especiales (a diferencia de Vue 2). Reemplazar el array entero (items.value = newArray) también funciona porque el setter del valor de la ref dispara la reactividad. filter/map producen arrays nuevos — asígnalos de vuelta para actualizar.

vue3
<script setup>
import { ref } from 'vue'

const items = ref([1, 2, 3])

// MUTATION methods (Vue 3 detects these via Proxy)
items.value.push(4)        // add
items.value.pop()          // remove last
items.value.splice(1, 1)   // remove at index
items.value.sort()         // sort

// REPLACEMENT (always reactive)
items.value = items.value.filter(n => n > 1)
items.value = [...items.value, 5]
</script>

TransitionGroup para listas

TransitionGroup anima listas v-for: entrada, salida Y movimiento (cuando los ítems cambian de posición). A diferencia de Transition, renderiza un elemento real (fjado vía tag). Cada hijo DEBE tener un :key único. La clase .list-move anima a los ítems deslizándose a sus nuevas posiciones cuando la lista se reordena — un efecto pulido que el CSS plano no puede lograr. leave-active necesita position: absolute para movimientos suaves.

vue3
<template>
  <TransitionGroup name="list" tag="ul">
    <li v-for="item in items" :key="item.id">
      {{ item.text }}
    </li>
  </TransitionGroup>
</template>

<style>
.list-enter-active, .list-leave-active {
  transition: all 0.5s ease;
}
.list-enter-from, .list-leave-to {
  opacity: 0;
  transform: translateX(30px);
}
/* animate items moving to new positions */
.list-move {
  transition: transform 0.5s ease;
}
</style>

Rendimiento: v-memo

v-memo es una pista de optimización. Vue se salta re-renderizar el elemento salvo que uno de los valores del array de dependencias cambie. Para listas grandes donde la mayoría de ítems no cambian en cada actualización, esto puede reducir dramáticamente los re-renders. Úsalo solo cuando hayas medido un problema de rendimiento — la optimización prematura añade complejidad y riesgo de UI obsoleta.

vue3
<template>
  <!-- skip re-render of this item unless 'id' or 'selected' changes -->
  <div
    v-for="item in hugeList"
    :key="item.id"
    v-memo="[item.id, item.id === selectedId]"
  >
    {{ item.name }} — {{ item.id === selectedId ? '★' : '' }}
  </div>
</template>
08

Manejo de eventos

Manejadores en línea

@click (abreviatura de v-on:click) enlaza un manejador de clic. Las sentencias en línea (count++) funcionan para casos simples. Un nombre de función (greet) recibe automáticamente el evento nativo como primer argumento. Para pasar argumentos personalizados Y el evento, llama a la función explícitamente con $event: greet('hi', $event).

vue3
<script setup>
import { ref } from 'vue'
const count = ref(0)
const name = ref('Vue')

function greet(event) {
  alert('Hello ' + name.value)
  // event is the native DOM event
  console.log(event.target.tagName)
}
</script>

<template>
  <!-- inline statement -->
  <button @click="count++">Add</button>

  <!-- method reference (auto-receives event) -->
  <button @click="greet">Greet</button>

  <!-- call with custom args (use $event for native event) -->
  <button @click="greet($event)">Greet</button>
</template>

Modificadores de eventos

Los modificadores de evento se encadenan tras el nombre del evento con un punto. .prevent y .stop son los más comunes (envío de formularios, burbujeo de eventos). .self garantiza que el manejador se dispare solo cuando se clic al propio elemento (no a un hijo). .passive le dice al navegador que el manejador no llamará a preventDefault, habilitando un scroll más suave — importante para manejadores táctiles/de scroll.

vue3
<template>
  <!-- .prevent: call preventDefault() -->
  <form @submit.prevent="onSubmit">...</form>

  <!-- .stop: call stopPropagation() -->
  <div @click="outer">
    <button @click.stop="inner">Won't bubble</button>
  </div>

  <!-- .self: only trigger if event.target === current element -->
  <div @click.self="onSelf">Only direct clicks</div>

  <!-- .once: handler removed after first invocation -->
  <button @click.once="init">Init once</button>

  <!-- .capture: use capture phase instead of bubble -->
  <div @click.capture="onCapture">...</div>

  <!-- .passive: improve scroll perf (no preventDefault) -->
  <div @scroll.passive="onScroll">...</div>
</template>

Modificadores de tecla y sistema

Los modificadores de tecla filtran eventos de teclado por nombre (.enter, .esc, .delete, .space, .tab, .up, .down, .left, .right). Los modificadores de sistema (.ctrl, .alt, .shift, .meta) exigen que esa tecla esté pulsada. .exact garantiza que no haya OTROS modificadores de sistema pulsados — @click.ctrl.exact se dispara solo en Ctrl+Clic, no en Ctrl+Shift+Clic. Usa kebab-case para las teclas que Vue no tiene en alias (page-down).

vue3
<template>
  <!-- key modifiers: only fire on specific keys -->
  <input @keyup.enter="submit" />
  <input @keyup.esc="cancel" />
  <input @keyup.delete="remove" />

  <!-- system modifiers: ctrl, alt, shift, meta -->
  <button @click.ctrl="openInNewTab">Ctrl+Click</button>
  <input @keyup.alt.enter="altEnter" />

  <!-- .exact: no other modifiers can be pressed -->
  <button @click.ctrl.exact="onCtrlOnly">Ctrl only</button>

  <!-- any key code via kebab-case (deprecated but works) -->
  <input @keyup.page-down="onPageDown" />
</template>

Eventos personalizados con emit

Los componentes hijos emiten eventos para comunicarse hacia arriba. defineEmits declara los nombres de los eventos (usado para validación y pistas del IDE). El padre escucha con @nombre-evento. Los payloads se pasan como argumentos adicionales a emit y los recibe el manejador del padre. Por convención, usa nombres de evento kebab-case en las plantillas (my-event) y camelCase en defineEmits (myEvent) — Vue los convierte automáticamente.

vue3
<!-- ChildButton.vue -->
<script setup>
const emit = defineEmits(['increment', 'delete'])

function onClick() {
  // emit with payload
  emit('increment', 1)
}
</script>

<template>
  <button @click="onClick">+1</button>
</template>

<!-- Parent.vue -->
<template>
  <ChildButton @increment="onIncrement" @delete="remove" />
</template>

<script setup>
function onIncrement(amount) {
  console.log('incremented by', amount)
}
</script>

v-model en componentes

defineModel() es la macro moderna (Vue 3.4+) para el binding bidireccional en componentes — devuelve una ref que se sincroniza automáticamente con el v-model del padre. Para varios bindings, usa modelos con nombre: v-model:nombreCampo. Por debajo esto emite 'update:modelValue' (o 'update:nombreCampo') y el padre sincroniza la ref enlazada. El código antiguo usa defineProps + defineEmits manualmente.

vue3
<!-- CustomInput.vue -->
<script setup>
const model = defineModel()
</script>

<template>
  <input :value="model" @input="model = $event.target.value" />
</template>

<!-- Parent.vue -->
<template>
  <CustomInput v-model="text" />
</template>

<!-- multiple v-models (Vue 3.4+) -->
<template>
  <UserForm v-model:name="name" v-model:email="email" />
</template>
09

Bindings de formularios

Text y textarea

v-model en inputs de texto sincroniza en cada evento input. Para textarea, pon v-model directamente en el elemento (no como :value — el contenido multilínea en un atributo no funciona). Modificadores: .lazy sincroniza en blur/change (menos actualizaciones), .trim recorta espacios, .number castea el valor a Number. Encadena modificadores: v-model.lazy.trim.

vue3
<script setup>
import { ref } from 'vue'
const text = ref('')
const message = ref('')
</script>

<template>
  <!-- text input: binds on every keystroke -->
  <input v-model="text" placeholder="Type here" />
  <p>You typed: {{ text }}</p>

  <!-- textarea: insert tags inside, not :value -->
  <textarea v-model="message" rows="4"></textarea>
  <p>Preview: {{ message }}</p>

  <!-- .lazy: sync on 'change' (blur) instead of 'input' -->
  <input v-model.lazy="text" />

  <!-- .trim: strip leading/trailing whitespace -->
  <input v-model.trim="text" />

  <!-- .number: cast to Number (NaN if invalid) -->
  <input v-model.number="age" type="number" />
</template>

Checkbox y radio

Un checkbox único se enlaza a un booleano (marcado = true). Varios checkboxes compartiendo el mismo v-model se enlazan a un array de sus atributos value — marcar añade el valor, desmarcar lo quita. Los radio buttons compartiendo un v-model enlazan el valor de la opción elegida a la ref. Usa los atributos true-value / false-value para personalizar el mapeo booleano.

vue3
<script setup>
import { ref } from 'vue'
const agreed = ref(false)
const fruits = ref([])     // array for multi-checkbox
const picked = ref('')     // string for radio
</script>

<template>
  <!-- single checkbox -> boolean -->
  <input type="checkbox" v-model="agreed" /> I agree

  <!-- multiple checkboxes with same v-model -> array -->
  <input type="checkbox" value="apple" v-model="fruits" /> Apple
  <input type="checkbox" value="banana" v-model="fruits" /> Banana
  <input type="checkbox" value="cherry" v-model="fruits" /> Cherry
  <p>Selected: {{ fruits }}</p>

  <!-- radio: value binds to the chosen option -->
  <input type="radio" value="A" v-model="picked" /> A
  <input type="radio" value="B" v-model="picked" /> B
</template>

Select

En <select>, v-model va en el elemento select (no en las options) y sincroniza con el valor de la opción elegida. Usa una opción placeholder disabled con valor vacío para la UX de 'selecciona, por favor'. Para opciones dinámicas, renderízalas con v-for y enlaza :value. Añade el atributo multiple para permitir la selección múltiple — v-model se enlaza entonces a un array de valores seleccionados.

vue3
<script setup>
import { ref } from 'vue'
const selected = ref('')
const multi = ref([])

const options = [
  { value: 'a', label: 'Option A' },
  { value: 'b', label: 'Option B' }
]
</script>

<template>
  <!-- single select -->
  <select v-model="selected">
    <option disabled value="">Please select</option>
    <option value="a">A</option>
    <option value="b">B</option>
  </select>

  <!-- dynamic options -->
  <select v-model="selected">
    <option v-for="opt in options" :key="opt.value" :value="opt.value">
      {{ opt.label }}
    </option>
  </select>

  <!-- multi-select (hold Ctrl/Cmd) -> array -->
  <select v-model="multi" multiple>
    <option value="x">X</option>
    <option value="y">Y</option>
  </select>
</template>

Envío y validación de formularios

Usa @submit.prevent para manejar el envío del formulario evitando la recarga de página por defecto. Los objetos de formulario reactivos agrupan campos relacionados. Para la validación, librerías como VeeValidate o Zod + un composable son populares en formularios complejos, pero una función validate() simple que devuelva un objeto de errores funciona bien en formularios pequeños. Prevén siempre el comportamiento por defecto para habilitar envíos estilo SPA.

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

const form = reactive({
  email: '',
  password: ''
})
const errors = ref({})

function validate() {
  errors.value = {}
  if (!form.email.includes('@')) errors.value.email = 'Invalid email'
  if (form.password.length < 6) errors.value.password = 'Too short'
  return Object.keys(errors.value).length === 0
}

function onSubmit() {
  if (!validate()) return
  // submit form...
}
</script>

<template>
  <form @submit.prevent="onSubmit">
    <input v-model.trim="form.email" />
    <span v-if="errors.email">{{ errors.email }}</span>

    <input type="password" v-model="form.password" />
    <span v-if="errors.password">{{ errors.password }}</span>

    <button type="submit">Submit</button>
  </form>
</template>

v-model con componentes personalizados

Envuelve los campos del formulario en componentes personalizados para reutilizarlos. defineModel() devuelve una ref que lee el valor del padre y escribe de vuelta vía el emit 'update:modelValue'. El componente enlaza :value al modelo y @input lo actualiza. Este patrón te permite construir un sistema de diseño consistente de inputs de formulario (BaseInput, BaseSelect, BaseCheckbox) usables con v-model igual que los elementos nativos.

vue3
<!-- BaseInput.vue -->
<script setup>
const model = defineModel()

defineProps({
  label: String,
  type: { type: String, default: 'text' }
})
</script>

<template>
  <label>
    {{ label }}
    <input
      :type="type"
      :value="model"
      @input="model = $event.target.value"
    />
  </label>
</template>

<!-- Usage -->
<template>
  <BaseInput v-model="email" label="Email" type="email" />
</template>
10

Componentes

Definir y usar componentes

Un componente es un archivo .vue con template, script y estilo opcional. Impórtalo (auto-registrado localmente en <script setup>) y úsalo como etiqueta HTML personalizada. Los nombres de componentes son PascalCase en el script y pueden ser kebab-case (my-button) en las plantillas — Vue los normaliza. Los componentes registrados globalmente (app.component) están disponibles en todas partes sin importar.

vue3
<!-- MyButton.vue -->
<template>
  <button class="btn"><slot /></button>
</template>

<!-- App.vue -->
<script setup>
import MyButton from './MyButton.vue'
</script>

<template>
  <MyButton>Click me</MyButton>
</template>

Componentes dinámicos

<component :is='...'> renderiza un componente dinámicamente — el valor puede ser una cadena de nombre registrado, un objeto de componente importado o un defineAsyncComponent. Envuélvelo en <keep-alive> para conservar el estado del componente (input de formulario, posición de scroll) al alternar entre pestañas. Usa shallowRef (no ref) para los objetos de componente y evitar la sobrecarga de reactividad profunda.

vue3
<script setup>
import { ref, shallowRef } from 'vue'
import HomeTab from './HomeTab.vue'
import PostsTab from './PostsTab.vue'
import ArchiveTab from './ArchiveTab.vue'

const tabs = { HomeTab, PostsTab, ArchiveTab }
const current = shallowRef('HomeTab')

// keep component state when switching (e.g. form input)
import { keep-alive } from 'vue' // not real — use the tag
</script>

<template>
  <button v-for="(comp, name) in tabs" :key="name" @click="current = name">
    {{ name }}
  </button>

  <keep-alive>
    <component :is="tabs[current]" />
  </keep-alive>
</template>

Componentes asíncronos

defineAsyncComponent carga un componente con pereza en el primer render — el fragmento se obtiene bajo demanda, reduciendo el tamaño del bundle inicial. Configura estados de carga/error para una UX suave. Combínalo con Suspense para coordinar varios componentes asíncronos. El loader devuelve una Promise del módulo del componente (Vite/Webpack dividen automáticamente según el import() dinámico).

vue3
<script setup>
import { defineAsyncComponent } from 'vue'

// lazy-load on first use (code-split)
const HeavyChart = defineAsyncComponent(() =>
  import('./HeavyChart.vue')
)

// with loading, error, delay, timeout states
const AdminPanel = defineAsyncComponent({
  loader: () => import('./AdminPanel.vue'),
  loadingComponent: LoadingSpinner,
  errorComponent: ErrorMsg,
  delay: 200,        // show loading after 200ms
  timeout: 5000      // error if not loaded in 5s
})
</script>

<template>
  <HeavyChart />
  <AdminPanel />
</template>

v-model de componente (múltiple)

Los modelos con nombre permiten que un solo componente exponga varios bindings bidireccionales. defineModel('nombre') declara cada uno. El padre usa v-model:nombre='...'. Esto es genial para componentes de formulario que agrupan varios campos (por ejemplo, un componente de dirección con calle, ciudad, código postal). El v-model por defecto (sin nombre) se mapea a 'modelValue'.

vue3
<!-- UserForm.vue -->
<script setup>
const firstName = defineModel('firstName')
const lastName = defineModel('lastName')
</script>

<template>
  <input v-model="firstName" />
  <input v-model="lastName" />
</template>

<!-- Parent.vue -->
<template>
  <UserForm
    v-model:firstName="form.first"
    v-model:lastName="form.last"
  />
</template>

Componentes recursivos y circulares

Un componente puede referenciarse a sí mismo por su nombre de archivo (autoautorreferencia). Es perfecto para estructuras de árbol (árboles de archivos, hilos de comentarios, menús). Para referencias circulares entre dos componentes (A importa B, B importa A), usa defineAsyncComponent para uno de ellos, o importa en beforeCreate. Vue maneja los componentes recursivos pero vigila los bucles infinitos — ten siempre un caso base (sin hijos).

vue3
<!-- TreeNode.vue -->
<script setup>
defineProps({
  node: Object
})

// a component can reference itself by its filename
// TreeNode.vue can use <TreeNode /> recursively
</script>

<template>
  <div>
    {{ node.label }}
    <ul v-if="node.children?.length">
      <li v-for="child in node.children" :key="child.id">
        <TreeNode :node="child" />
      </li>
    </ul>
  </div>
</template>
11

Props

Declarar props

defineProps declara el contrato de entrada de un componente. La declaración en runtime soporta type, default, required y validator. La declaración basada en tipos de Vue 3 (solo TS) da seguridad de tipos pero pierde la validación de runtime (úsala con volar + una librería validadora). Los valores por defecto de objetos/arrays deben usar una función factoría: default: () => [].

vue3
<script setup>
// runtime declaration (validates types)
const props = defineProps({
  title: String,
  count: { type: Number, default: 0 },
  items: { type: Array, required: true },
  callback: { type: Function, default: () => {} },
  status: {
    type: String,
    validator: (v) => ['active', 'idle'].includes(v)
  }
})

// type-based declaration (TS only, no runtime validation)
const props2 = defineProps<{
  title: string
  count?: number
}>()
</script>

Nombrado y paso de props

Las props deberían ser camelCase en JS (greetingMessage) y kebab-case en las plantillas (greeting-message) — el HTML no distingue mayúsculas así que kebab-case es más seguro. Vue convierte automáticamente entre ambas. Las props de cadena estáticas usan sintaxis de atributo plano; los valores dinámicos usan :prop. Pasa números/booleanos/objetos siempre con : para que no se traten como cadenas.

vue3
<!-- Child.vue -->
<script setup>
defineProps({
  greetingMessage: String,
  userId: Number
})
</script>

<!-- Parent.vue -->
<template>
  <!-- kebab-case in templates (HTML-friendly) -->
  <Child greeting-message="Hello" :user-id="42" />

  <!-- camelCase also works in SFC templates -->
  <Child greetingMessage="Hello" :userId="42" />
</template>

Flujo de datos unidireccional

Las props son de solo lectura — nunca las mutés directamente. Vue advierte en modo dev. Para cambiar el valor de una prop, emite un evento y deja que el padre lo actualice (flujo de datos unidireccional). Para una copia de trabajo local, inicializa una ref desde la prop y sincroniza vía watch. El patrón bidireccional más limpio es v-model con defineModel, que abstrae la danza de emitir-y-actualizar.

vue3
<!-- BAD: mutating a prop -->
<script setup>
const props = defineProps(['count'])

function inc() {
  props.count++  // WARNING: don't mutate props!
}
</script>

<!-- GOOD: emit to parent, or use local copy -->
<script setup>
import { ref, watch } from 'vue'
const props = defineProps(['count'])
const emit = defineEmits(['update:count'])

// local copy that syncs with prop
const local = ref(props.count)
watch(() => props.count, v => local.value = v)

function inc() {
  local.value++
  emit('update:count', local.value)
}
</script>

Validación y valores por defecto de props

Vue valida las props en modo dev y advierte ante fallo (no en producción). type acepta un constructor (String, Number, Boolean, Array, Object, Function, Symbol) o un array de ellos. Los valores por defecto de Object y Array DEBEN ser funciones que devuelvan una nueva instancia — de lo contrario la totalidad de los componentes compartirían la misma referencia por defecto (bugs de mutación). Los validadores corren tras las comprobaciones de tipo.

vue3
<script setup>
const props = defineProps({
  // type can be an array of allowed types
  value: { type: [String, Number], required: true },

  // object/array default MUST be a factory function
  list: {
    type: Array,
    default: () => []
  },

  // custom validator
  age: {
    type: Number,
    validator: (v) => v >= 0 && v <= 150
  },

  // multiple checks combined
  email: {
    type: String,
    required: true,
    validator: (v) => v.includes('@')
  }
})
</script>

Casting booleano y caída de atributos

Las props booleanas tienen un casting especial: la presencia sin valor significa true. La caída de atributos pasa los atributos no-prop (class, style, id, data-*) al elemento raíz automáticamente. Múltiples raíces exigen v-bind='$attrs' explícito sobre el elemento deseado. Desactiva la caída con defineOptions({ inheritAttrs: false }) para control total.

vue3
<!-- prop declared as Boolean -->
<script setup>
defineProps({
  disabled: Boolean,
  active: Boolean
})
</script>

<!-- Parent -->
<template>
  <MyButton disabled />       <!-- disabled = true -->
  <MyButton :disabled="false" /> <!-- disabled = false -->
  <MyButton />                <!-- disabled = undefined -->
</template>

<!-- Attribute fallthrough: non-prop attributes
     land on the root element automatically -->
<template>
  <!-- <MyButton data-id="5" class="large" /> -->
  <!-- the data-id and class merge onto the <button> root -->
  <button>...</button>
</template>
12

Emits

Declarar y emitir

defineEmits declara los eventos que un componente puede emitir. La forma de objeto permite validadores que reciben el payload y devuelven false para advertir (modo dev). Los emits suben por el árbol — los padres escuchan con @nombre-evento. Declara siempre los emits explícitamente: documenta la API, habilita la exclusión de la caída de atributos y soporta validación. emit() toma el nombre del evento más argumentos de payload opcionales.

vue3
<script setup>
// declare emits (with optional validation)
const emit = defineEmits({
  // null-ish = no validation
  click: null,

  // function = validate payload
  submit: (payload) => {
    if (!payload.email) {
      console.warn('submit needs email')
      return false
    }
    return true
  }
})

function handleSubmit() {
  emit('submit', { email: '[email protected]', name: 'Alice' })
}
</script>

Escuchar los emits

Los padres escuchan con @nombre-evento (o v-on:nombre-evento). El manejador recibe cualquier payload emitido. Las funciones flecha en línea son prácticas para transformaciones simples (@increment='n => count += n'). Los manejadores de función reciben automáticamente el payload como primer argumento. Los eventos nativos del DOM sobre el elemento raíz de un componente caen hacia abajo salvo que se declaren en emits — declarar 'click' lo convierte en evento personalizado.

vue3
<!-- Child.vue -->
<script setup>
const emit = defineEmits(['increment', 'delete'])

function click() {
  emit('increment', 5)
}
</script>

<template>
  <button @click="click">+5</button>
</template>

<!-- Parent.vue -->
<template>
  <!-- inline handler -->
  <Child @increment="n => count += n" />

  <!-- method handler -->
  <Child @increment="onIncrement" @delete="onDelete" />
</template>

<script setup>
function onIncrement(amount) {
  console.log('incremented by', amount)
}
</script>

Implementación de v-model

v-model sobre un componente es azúcar de :modelValue + @update:modelValue. El hijo recibe el valor vía una prop modelValue y emite update:modelValue para sincronizar. Este es el patrón manual; defineModel() (Vue 3.4+) lo envuelve. Para v-model con nombre (v-model:foo), usa la prop foo y el evento update:foo. Esto habilita construir componentes de formulario que funcionen como inputs nativos.

vue3
<!-- CustomInput.vue (manual implementation) -->
<script setup>
const props = defineProps(['modelValue'])
const emit = defineEmits(['update:modelValue'])

function onInput(e) {
  emit('update:modelValue', e.target.value)
}
</script>

<template>
  <input
    :value="modelValue"
    @input="onInput"
  />
</template>

<!-- Parent -->
<template>
  <CustomInput v-model="text" />
</template>

Validación de emits

Los validadores de emit reciben los argumentos del payload y devuelven false para disparar una advertencia en modo dev. No impiden el emit — solo advierten. Esto atrapa temprano las violaciones de contrato en desarrollo. Úsalos para documentar las formas de payload esperadas. En producción, los validadores se eliminan, así que no dependas de ellos para seguridad o flujo de control.

vue3
<script setup>
const emit = defineEmits({
  // no validation
  click: null,

  // validate payload; return false to warn
  change: (value) => {
    if (typeof value !== 'string') {
      console.warn('change payload must be string')
      return false
    }
    return true
  },

  // validate multiple args
  update: (id, value) => {
    if (!id || value === undefined) return false
    return true
  }
})

// validation runs on emit
emit('change', 123)  // warns: must be string
</script>

Eventos vs props: cuándo usar cada uno

Sigue el flujo de datos unidireccional: props hacia abajo, eventos hacia arriba. Para el binding bidireccional, usa v-model (azúcar de props + emit). Para la comunicación profundamente anidada, la perforación de props se vuelve dolorosa — usa provide/inject para la inyección de dependencias o un store (Pinia) para el estado compartido. Los eventos son para notificaciones de 'algo pasó'; las props para 'aquí tienes tus datos'.

vue3
<!-- Parent-to-child: props (down) -->
<template>
  <Child :data="parentData" :config="config" />
</template>

<!-- Child-to-parent: emits (up) -->
<template>
  <Child @change="onChange" @submit="onSubmit" />
</template>

<!-- Two-way: v-model (combines both) -->
<template>
  <Child v-model="value" />
</template>

<!-- For complex state, prefer provide/inject or a store -->
13

Slots

Slot por defecto

Los slots permiten a un padre inyectar contenido en la plantilla de un componente hijo. El elemento <slot> es el marcador. El contenido hijo del padre llena el slot por defecto. Los slots habilitan la composición: Card maneja el estilo del envoltorio y el padre controla el contenido interior. Sin slots necesitarías una prop por cada posible elemento interior — los slots son mucho más flexibles.

vue3
<!-- Card.vue -->
<template>
  <div class="card">
    <slot />
  </div>
</template>

<!-- Usage -->
<template>
  <Card>
    <p>This goes into the default slot</p>
    <button>Action</button>
  </Card>
</template>

Slots con nombre

Los slots con nombre permiten que un componente tenga varios marcadores de contenido. Declara con <slot name='foo' /> y llena con <template #foo>. La # es abreviatura de v-slot:. El slot sin nombre es el slot 'default' — el contenido sin envoltorio de template va ahí. Los slots con nombre son perfectos para layouts (header, sidebar, main, footer) donde el padre llena cada región.

vue3
<!-- Layout.vue -->
<template>
  <header><slot name="header" /></header>
  <main><slot /></main>
  <footer><slot name="footer" /></footer>
</template>

<!-- Usage with # shorthand -->
<template>
  <Layout>
    <template #header>
      <h1>My Page Title</h1>
    </template>

    <!-- default slot (no #name) -->
    <p>Main content here</p>

    <template #footer>
      <p>© 2025</p>
    </template>
  </Layout>
</template>

Slot props (slots acotados)

Los slots acotados permiten a un hijo pasar datos de vuelta al contenido del slot del padre. El hijo enlaza datos sobre <slot :item='item'>; el padre los recibe vía v-slot='{ item }' (o #default='{ item }'). Es la fundación de los componentes de lista reutilizables (tabla de datos, lista virtual): el hijo maneja la iteración y el padre controla el renderizado de cada ítem.

vue3
<!-- List.vue -->
<template>
  <ul>
    <li v-for="item in items" :key="item.id">
      <slot :item="item" :index="index" />
    </li>
  </ul>
</template>

<script setup>
defineProps(['items'])
</script>

<!-- Usage: receive slot props via v-slot -->
<template>
  <List :items="todos">
    <template #default="{ item, index }">
      <input type="checkbox" v-model="item.done" />
      <span :class="{ done: item.done }">{{ index }}: {{ item.text }}</span>
    </template>
  </List>
</template>

Contenido por defecto del slot

El contenido de respaldo del slot va entre <slot> y </slot>. Se renderiza solo cuando el padre no proporciona contenido de slot. Es genial para valores por defecto sensatos — una etiqueta de botón, un mensaje de estado vacío, un marcador. Si el padre pasa incluso una cadena vacía, el respaldo queda anulado.

vue3
<!-- Button.vue -->
<template>
  <button>
    <slot>Click here</slot>  <!-- fallback content -->
  </button>
</template>

<!-- Usage -->
<template>
  <Button />             <!-- renders "Click here" -->
  <Button>Save</Button>  <!-- renders "Save" -->
</template>

Ámbito de renderizado y uso de slots

El contenido del slot se renderiza en el ámbito del PADRE — puede acceder al estado del padre pero no directamente al del hijo (salvo vía slot props). Esta separación deja a un hijo manejar la mecánica (paginación, virtualización, peticiones) mientras el padre controla la presentación. El patrón de slot acotado (FancyList + UserCard) es una técnica de composición potente — el hijo posee el flujo de datos, el padre el renderizado.

vue3
<!-- FancyList.vue (scoped slot pattern) -->
<script setup>
const props = defineProps(['items', 'pageSize'])
import { ref, computed } from 'vue'

const page = ref(1)
const paged = computed(() =>
  props.items.slice((page.value - 1) * props.pageSize, page.value * props.pageSize)
)
</script>

<template>
  <div v-for="item in paged" :key="item.id">
    <slot :item="item" :page="page" />
  </div>
</template>

<!-- Usage: parent fully controls rendering -->
<FancyList :items="users" :pageSize="10">
  <template #default="{ item, page }">
    <UserCard :user="item" />
    <small>Page {{ page }}</small>
  </template>
</FancyList>
14

Hooks del ciclo de vida

Hooks de la Composition API

Los hooks del ciclo de vida corren en etapas concretas. onMounted se dispara tras renderizarse el DOM (seguro para acceder a elementos, correr librerías de canvas, pedir datos). onUpdated se dispara tras cada actualización reactiva — evita mutar estado aquí (bucle infinito). onUnmounted es para limpieza (temporizadores, listeners, suscripciones). Los hooks deben llamarse sincrónicamente en el setup, pero pueden llamarse varias veces.

vue3
<script setup>
import {
  onBeforeMount, onMounted,
  onBeforeUpdate, onUpdated,
  onBeforeUnmount, onUnmounted,
  onActivated, onDeactivated,
  onErrorCaptured
} from 'vue'

onBeforeMount(() => console.log('before mount'))
onMounted(() => console.log('mounted — DOM ready'))
onBeforeUpdate(() => console.log('before re-render'))
onUpdated(() => console.log('after re-render'))
onBeforeUnmount(() => console.log('before unmount'))
onUnmounted(() => console.log('unmounted — cleanup'))
</script>

Setup vs created

En <script setup>, la totalidad del cuerpo del script corre durante la inicialización del componente — equivalente a beforeCreate + created en la Options API. No hay hook created() separado. El código de nivel superior (declaraciones, llamadas a funciones, incluso trabajo asíncrono) corre una vez por instancia. Para pedir datos, este es un lugar común para empezar (aunque onMounted también está bien — la petición empieza igual de cualquier forma).

vue3
<script setup>
// <script setup> runs BEFORE the component is mounted
// (equivalent to beforeCreate + created in Options API)

import { ref } from 'vue'

// this code runs once per component instance,
// before reactive state is exposed to the template
const count = ref(0)
console.log('component created, count =', count.value)

// no need for created() hook — just run code here
fetch('/api/data')
  .then(r => r.json())
  .then(data => { /* ... */ })
</script>

Mounted y limpieza

Los pares de setup/limpieza son esenciales: cada listener, temporizador, suscripción u observador añadido en onMounted DEBE eliminarse en onUnmounted. No limpiar causa fugas de memoria y manejadores zombis disparándose sobre componentes destruidos. El patrón: addEventListener en onMounted, removeEventListener en onUnmounted. Para los watchers, usa la función stop devuelta o se auto-limpian al desmontar.

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

const windowWidth = ref(window.innerWidth)

function onResize() {
  windowWidth.value = window.innerWidth
}

onMounted(() => {
  // setup side effects after DOM is ready
  window.addEventListener('resize', onResize)
  console.log('mounted')
})

onUnmounted(() => {
  // ALWAYS clean up to avoid memory leaks
  window.removeEventListener('resize', onResize)
})
</script>

Hooks de KeepAlive

Cuando un componente está envuelto en <KeepAlive>, cambiarse no lo desmonta — se desactiva (cacheado). onActivated y onDeactivated se disparan al mostrarse/ocultarse. Úsalos para pausar/reanudar trabajo (polling, reproducción de vídeo) sin setup/teardown completos. onMounted aún se dispara una vez (primera activación); onUnmounted nunca se dispara mientras esté cacheado. Estos hooks te permiten optimizar el uso de recursos en pestañas cacheadas.

vue3
<script setup>
import { onActivated, onDeactivated } from 'vue'

// these fire when the component is wrapped in <KeepAlive>
// and is being shown (activated) or hidden (deactivated)
onActivated(() => {
  console.log('component shown again — resume polling')
  startPolling()
})

onDeactivated(() => {
  console.log('component hidden but not unmounted — pause')
  stopPolling()
})

// onMounted fires only once (first show)
// onActivated fires every time it's re-shown
</script>

Error captured

onErrorCaptured atrapa errores de componentes descendientes (en plantillas, render, ciclo de vida, watchers). Recibe (error, instancia, info). Devuelve false para impedir que el error se propague a los manejadores errorCaptured de los padres y al errorHandler global. Úsalo para componentes frontera que manejen con elegancia los errores de los hijos (como los Error Boundaries de React). Combínalo con Suspense para los estados de error asíncronos.

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

const error = ref(null)

onErrorCaptured((err, instance, info) => {
  // err: the error thrown
  // instance: component that threw
  // info: lifecycle hook or event name where it occurred
  error.value = err.message
  console.error('Captured:', err, info)

  // return false to stop propagation to parent
  return false
})
</script>

<template>
  <div v-if="error" class="error">{{ error }}</div>
  <slot v-else />
</template>
15

Composition API

ref vs reactive

ref() funciona con cualquier valor (primitivos, objetos). El acceso reactivo exige .value en JS, pero auto-desenvuelve en las plantillas. reactive() solo funciona en objetos/arrays — no necesita .value. Usa ref para primitivos y valores reemplazables; usa reactive para estado agrupado. Regla práctica: prefiere ref() para valores individuales, reactive() para objetos de estado. Mezclar está bien — las refs se auto-desenvuelven dentro de objetos reactivos.

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

// ref: works with any value, access via .value
const count = ref(0)
count.value++
console.log(count.value)  // 1

// reactive: only for objects/arrays, no .value needed
const state = reactive({ count: 0, user: { name: 'A' } })
state.count++
console.log(state.count)  // 1

// refs auto-unwrap in templates and reactive objects
const wrapper = reactive({ count })  // wrapper.count === count.value
</script>

Trampas de reactive

Los objetos reactivos tienen dos trampas: no puedes reasignar la variable (state = newObj) — muta propiedades en su lugar (state.list = []). La desestructuración pierde reactividad porque la variable desestructurada es una instantánea. Usa toRefs() para convertir las propiedades reactivas en refs que sigan enlazadas. Estas trampas son la razón por la que muchos desarrolladores prefieren ref() — es reemplazable (solo fja .value) y amigable con la desestructuración.

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

const state = reactive({ list: [1, 2, 3] })

// PITFALL 1: replacing the whole object loses reactivity
// state = reactive({ list: [4, 5] })  // ERROR: reassign

// GOOD: mutate properties
state.list = [4, 5]

// PITFALL 2: destructuring loses reactivity
let { list } = state  // 'list' is now plain
// list.push(4) won't trigger updates

// FIX: use toRefs to keep reactivity
import { toRefs } from 'vue'
const { list } = toRefs(state)  // now list is a ref
</script>

toRef y toRefs

toRef() convierte una única propiedad reactiva en una ref que sigue enlazada (mutar cualquiera afecta a la otra). toRefs() convierte TODAS las propiedades — útil para devolver estado reactivo desde composables conservando la desestructuración. Sin toRefs, los valores desestructurados pierden reactividad. Patrón: el composable devuelve toRefs(state) para que los consumidores puedan desestructurar sin romper la reactividad.

vue3
<script setup>
import { reactive, toRef, toRefs } from 'vue'

const state = reactive({
  count: 0,
  name: 'Alice'
})

// toRef: single property -> ref (stays linked to state)
const countRef = toRef(state, 'count')

// toRefs: all properties -> object of refs
const { count, name } = toRefs(state)

countRef.value++      // updates state.count
count.value++         // also updates state.count
console.log(state.count)  // 2
</script>

computed y watch en setup

En <script setup>, computed() y watch() se importan y se llaman directamente. computed crea una ref derivada; watch corre un callback al cambiar la fuente. watch puede tomar una única ref, un getter, un array de fuentes o un objeto reactivo. Estos son las primitivas centrales de la Composition API — combínalos para encapsular lógica en composables.

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

const a = ref(1)
const b = ref(2)

// computed: derived value, cached
const sum = computed(() => a.value + b.value)

// watch: side effect on change
watch(sum, (newSum) => {
  console.log('sum changed to', newSum)
})

// watch multiple sources
watch([a, b], ([newA, newB]) => {
  console.log('a or b changed:', newA, newB)
})
</script>

shallowRef y shallowReactive

shallowRef y shallowReactive renuncian a la reactividad profunda — solo la referencia/propiedades de nivel superior se rastrean. Esto mejora dramáticamente el rendimiento en estructuras de datos grandes (por ejemplo, el array de datos de un gráfico, un grafo de escena 3D) donde el rastreo profundo es un desperdicio. Usa triggerRef() para notificar manualmente a Vue tras una mutación profunda. Recurre a estos solo cuando hayas medido un problema de rendimiento.

vue3
<script setup>
import { shallowRef, shallowReactive, triggerRef } from 'vue'

// shallowRef: only .value changes trigger updates
// (deep changes to .value properties do NOT)
const big = shallowRef({ items: [1, 2, 3] })
big.value.items.push(4)       // NO update triggered
big.value = { items: [1,2,3,4] }  // update triggered

// force update after deep mutation
big.value.items.push(5)
triggerRef(big)  // tells Vue to re-render

// shallowReactive: only root-level props are reactive
const state = shallowReactive({ user: { name: 'A' } })
state.count = 1            // reactive
state.user.name = 'B'      // NOT reactive
</script>
16

Composables

Escribir un composable

Un composable es una función que encapsula lógica reactiva reutilizable. Por convención, nómbrala useAlgo. Usa hooks de la Composition API (onMounted, etc.) que se enlazan al ciclo de vida del componente consumidor. Devuelve refs y funciones. El componente los desestructura. Los composables son el equivalente Vue de los hooks de React — te permiten compartir lógica con estado sin render props ni HOCs.

vue3
<!-- useMousePosition.js -->
import { ref, onMounted, onUnmounted } from 'vue'

export function useMousePosition() {
  const x = ref(0)
  const y = ref(0)

  function update(e) {
    x.value = e.pageX
    y.value = e.pageY
  }

  onMounted(() => window.addEventListener('mousemove', update))
  onUnmounted(() => window.removeEventListener('mousemove', update))

  return { x, y }
}

<!-- In component -->
<script setup>
import { useMousePosition } from './useMousePosition'
const { x, y } = useMousePosition()
</script>

Composable con estado (estado compartido)

Cuando el estado se declara a nivel de módulo (fuera de la función), es un singleton — la totalidad de los componentes que usan el composable comparten el mismo estado. Es una alternativa ligera a Pinia para un estado global simple. Usa readonly() para exponer el estado sin permitir la mutación directa — los componentes deben llamar a login/logout para cambiarlo. Para apps complejas, prefiere Pinia (mejores devtools, persistencia, soporte SSR).

vue3
<!-- useUser.js -->
import { reactive, readonly } from 'vue'

// module-scoped state — shared across all consumers
const state = reactive({
  user: null,
  loading: false
})

export function useUser() {
  async function login(credentials) {
    state.loading = true
    state.user = await fetch('/api/login', {
      method: 'POST',
      body: JSON.stringify(credentials)
    }).then(r => r.json())
    state.loading = false
  }

  function logout() {
    state.user = null
  }

  return {
    user: readonly(state.user),  // expose read-only
    loading: readonly(state.loading),
    login,
    logout
  }
}

Composable useFetch

Este composable envuelve a fetch con estado de carga/error y vuelve a pedir cuando una url reactiva cambia. isRef() comprueba si la entrada es una ref; unref() la desenvuelve (devuelve el valor para las refs, identidad de lo contrario). Devolver refresh permite al consumidor volver a pedir manualmente. Este patrón (entrada reactiva + re-corrida automática + exponer estado) es el pan de cada día de los composables para pedir datos.

vue3
<!-- useFetch.js -->
import { ref, watchEffect, isRef, unref } from 'vue'

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

  async function doFetch() {
    loading.value = true
    error.value = null
    try {
      const res = await fetch(unref(url))
      if (!res.ok) throw new Error('HTTP ' + res.status)
      data.value = await res.json()
    } catch (e) {
      error.value = e.message
    } finally {
      loading.value = false
    }
  }

  // re-fetch when url ref changes
  if (isRef(url)) {
    watchEffect(doFetch)
  } else {
    doFetch()
  }

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

Composable con limpieza

Los composables que registran efectos secundarios (listeners, temporizadores, suscripciones) DEBEN limpiar — típicamente vía onUnmounted dentro del composable. Esto enlaza la limpieza a cualquier componente que consuma el composable, de modo que el consumidor no tenga que recordarlo. Es una ventaja mayor de los composables frente a las funciones de utilidad: participan en el ciclo de vida del componente.

vue3
<!-- useEventListener.js -->
import { onUnmounted } from 'vue'

export function useEventListener(target, event, callback) {
  target.addEventListener(event, callback)

  // auto-cleanup when the consuming component unmounts
  onUnmounted(() => {
    target.removeEventListener(event, callback)
  })
}

<!-- Usage -->
<script setup>
import { useEventListener } from './useEventListener'
import { ref } from 'vue'

const key = ref('')
useEventListener(window, 'keydown', (e) => {
  key.value = e.key
})
// listener is removed automatically on unmount
</script>

Convenciones de los composables

Sigue estas convenciones: (1) nombra los composables con el prefijo use; (2) devuelve refs (no valores planos — los valores planos pierden reactividad); (3) acepta refs o getters como entradas por flexibilidad; (4) usa onUnmounted para la limpieza; (5) mantenlos enfocados (una preocupación por composable). Estas convenciones hacen que los composables sean componibles entre sí y predecibles de usar.

vue3
<!-- DO: name with 'use' prefix, return refs -->
export function useCounter(initial = 0) {
  const count = ref(initial)
  const inc = () => count.value++
  const dec = () => count.value--
  return { count, inc, dec }
}

<!-- AVOID: returning plain values (loses reactivity) -->
export function badCounter() {
  let count = 0  // plain variable — NOT reactive!
  return { count, inc: () => count++ }
}

<!-- DO: accept refs/getters for flexible inputs -->
export function useSearch(query) {
  // query can be a ref, a getter, or a plain value
  return watchEffect(() => fetch('/api?q=' + unref(query)))
}
17

Reactividad en profundidad

Mecánica de proxies reactivos

La reactividad de Vue 3 usa Proxy (ES6). reactive() devuelve un Proxy que intercepta get (para rastrear dependencias) y set (para disparar actualizaciones). El objeto original no se modifica — obtienes una versión envuelta. isReactive() comprueba si algo es un proxy reactivo. Es más potente que el enfoque de Object.defineProperty de Vue 2, que no podía detectar la adición de propiedades nuevas.

vue3
<script setup>
import { reactive, isReactive, isProxy } from 'vue'

const state = reactive({ count: 0 })

// reactive() wraps the object in a Proxy
// reads/writes are tracked and trigger updates
state.count++  // triggers re-render

// the original object is NOT reactive
const raw = { count: 0 }
const wrapped = reactive(raw)
console.log(raw === wrapped)         // false
console.log(isReactive(wrapped))     // true
console.log(isReactive(raw))         // false
console.log(isProxy(wrapped))        // true
</script>

Reglas de desenvuelto de las refs

Reglas de desenvuelto de las refs: en <script>, accede vía .value; en las plantillas y dentro de objetos reactivos, las refs se auto-desenvuelven a su .value. Por eso {{ count }} en una plantilla funciona sin .value. El auto-desenvuelto es superficial — las refs anidadas en arrays/Maps no se desenvuelven. Los objetos reactivos que contienen refs mutan el valor de la ref al asignar: state.count = 5 fija count.value = 5.

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

const count = ref(0)
const state = reactive({ count })

// in JS: ref needs .value
count.value = 1

// in reactive object: ref auto-unwraps
console.log(state.count)  // 1 (not count.value)
state.count = 5           // updates count.value

// in templates: ref auto-unwraps
// {{ count }} renders count.value
</script>

<template>
  <p>{{ count }}</p>  <!-- 5, not [object Object] -->
</template>

Effect y track/trigger (internos)

effect() es la primitiva de bajo nivel detrás de la reactividad — corre una función, rastrea cada lectura reactiva dentro y vuelve a correr cuando cualquier valor rastreado cambia. computed, watch, watchEffect y el renderizado de componentes se construyen sobre effect. Rara vez llamas a effect() directamente en el código de la app — prefiere computed/watch/watchEffect — pero es el motor. Entenderlo ayuda a razonar sobre el reordenamiento y los tiempos.

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

const count = ref(0)

// effect runs immediately, then re-runs on dep change
effect(() => {
  console.log('count is', count.value)
})
// logs: count is 0

count.value = 10
// logs: count is 10

// internally:
// - effect tracks dependencies accessed inside it
// - setting count.value triggers all tracked effects
</script>

markRaw y readonly

markRaw() saca permanentemente un objeto de la reactividad — útil para instancias de clases de terceros (gráficos, mapas, estado de juego) que tienen sus propios mecanismos de actualización y no deberían envolverse en un Proxy. readonly() crea una vista de solo lectura de un objeto reactivo — los intentos de mutación advierten en modo dev. Usa readonly para exponer estado desde composables/stores impidiendo la mutación directa.

vue3
<script setup>
import { reactive, markRaw, readonly, isReadonly } from 'vue'

// markRaw: opt a value OUT of reactivity forever
const bigChart = markRaw(new HeavyChartLib())
const state = reactive({ chart: bigChart })
// state.chart mutations won't trigger Vue updates
// (use chart's own API to update it)

// readonly: make a reactive object read-only
const original = reactive({ count: 0 })
const frozen = readonly(original)
frozen.count = 5
// warning: target is readonly (dev mode)

console.log(isReadonly(frozen))  // true
</script>

Ref personalizada (factoría)

customRef() te permite controlar el rastreo de dependencias y el disparo explícitamente. La factoría recibe track() y trigger() — llama a track() en get() para registrar la dependencia, llama a trigger() en set() para notificar las actualizaciones. Esto habilita patrones como refs con debounce, refs perezosas o refs respaldadas por almacenamiento. Potente pero úsalo con moderación — normalmente watchEffect + una ref normal es más claro.

vue3
<script setup>
import { customRef } from 'vue'

// debounce a ref's updates
function debouncedRef(value, delay = 200) {
  let timeout
  return customRef((track, trigger) => ({
    get() {
      track()  // tell Vue this value is a dependency
      return value
    },
    set(newValue) {
      clearTimeout(timeout)
      timeout = setTimeout(() => {
        value = newValue
        trigger()  // notify Vue of the change
      }, delay)
    }
  }))
}

const text = debouncedRef('', 300)
// input only triggers re-render 300ms after typing stops
</script>
18

Vue Router

Configuración del router

createRouter configura el enrutado. createWebHistory usa el modo de historial HTML5 (URLs limpias, exige que el servidor recurrta a index.html). Carga los componentes de ruta con pereza mediante import() dinámico para dividir el código — cada ruta se vuelve su propio bundle. Los segmentos dinámicos (:id) se acceden vía route.params. Instala el router como plugin con app.use(router).

vue3
<!-- router/index.js -->
import { createRouter, createWebHistory } from 'vue-router'
import Home from '../views/Home.vue'

const routes = [
  { path: '/', name: 'home', component: Home },
  {
    path: '/about',
    name: 'about',
    // lazy-load for code-splitting
    component: () => import('../views/About.vue')
  },
  { path: '/user/:id', name: 'user', component: () => import('../views/User.vue') }
]

export const router = createRouter({
  history: createWebHistory(),
  routes
})

<!-- main.js -->
import { createApp } from 'vue'
import App from './App.vue'
import { router } from './router'

createApp(App).use(router).mount('#app')

RouterView y RouterLink

<RouterView> es el marcador donde se renderiza el componente de la ruta emparejada. <RouterLink> renderiza una etiqueta <a> pero intercepta los clics para la navegación del lado del cliente (sin recarga completa de página). La prop to acepta una cadena de ruta o un objeto ({ name, params, query }). RouterLink añade las clases active/exact-active para estilizar el enlace actual.

vue3
<!-- App.vue -->
<template>
  <nav>
    <!-- RouterLink renders <a>, handles navigation -->
    <RouterLink to="/">Home</RouterLink>
    <RouterLink to="/about">About</RouterLink>
    <RouterLink :to="{ name: 'user', params: { id: 42 } }">
      User 42
    </RouterLink>
  </nav>

  <!-- matched route's component renders here -->
  <RouterView />
</template>

Navegación y enrutado programático

useRouter() da la instancia del router para navegar; useRoute() da la ruta actual (reactiva). push añade una entrada de historial (el botón atrás funciona); replace no. Las propiedades de la ruta (path, params, query, hash, name, matched) son reactivas — los watchers y computed vuelven a correr al navegar. Usa siempre router.push para navegar dentro de la app — nunca window.location para mantener la SPA.

vue3
<script setup>
import { useRouter, useRoute } from 'vue-router'

const router = useRouter()
const route = useRoute()

// push to a new URL (adds to history)
function goHome() {
  router.push('/')
  router.push({ name: 'user', params: { id: 1 } })
  router.push({ path: '/search', query: { q: 'vue' } })
}

// replace current entry (no back button)
router.replace('/login')

// go back/forward
router.back()
router.forward()
router.go(-2)

// access current route info
console.log(route.path, route.params.id, route.query.q)
</script>

Guards de ruta

Los guards controlan el flujo de navegación. El beforeEach global es genial para las comprobaciones de autenticación. El beforeEnter por ruta protege rutas concretas. Los guards dentro del componente (onBeforeRouteLeave, onBeforeRouteUpdate) son útiles para avisos de cambios sin guardar. Devuelve false o una ruta para cancelar/redirigir; devuelve true/undefined para confirmar. Los guards asíncronos pueden devolver una Promise. Usa route.meta para adjuntar flags como requiresAuth.

vue3
<!-- router/index.js -->
const router = createRouter({ history, routes })

// global guard: runs on every navigation
router.beforeEach((to, from) => {
  if (to.meta.requiresAuth && !isAuthenticated()) {
    return '/login'  // redirect
  }
  // return true or undefined to confirm
})

// per-route guard
{ path: '/admin', component: Admin, beforeEnter: (to, from) => {
  if (!isAdmin()) return '/403'
}}

// in-component guard
<script setup>
import { onBeforeRouteLeave } from 'vue-router'
onBeforeRouteLeave((to, from) => {
  if (hasUnsavedChanges()) {
    return confirm('Discard changes?')
  }
})
</script>

Carga perezosa y rutas anidadas

Las rutas anidadas renderizan componentes hijos dentro del <RouterView> del padre. Define los children con rutas relativas al padre. La ruta vacía ('') coincide exactamente con la URL del padre. El import() dinámico divide el código de cada ruta en su propio bundle. Usa route.meta para adjuntar datos (requisitos de auth, títulos) — accesibles en los guards vía to.meta. Agrupa las rutas relacionadas con un comentario de nombre de fragmento.

vue3
const routes = [
  {
    path: '/dashboard',
    component: () => import('../views/Dashboard.vue'),
    children: [
      { path: '', component: () => import('../views/Overview.vue') },
      { path: 'stats', component: () => import('../views/Stats.vue') },
      { path: 'settings', component: () => import('../views/Settings.vue') }
    ]
  },
  // group routes into one chunk
  {
    path: '/admin',
    component: () => import(/* webpackChunkName: "admin" */ '../views/Admin.vue'),
    meta: { requiresAuth: true, role: 'admin' }
  }
]
19

Gestión de estado (Pinia)

Definir un store

Pinia es la gestión de estado oficial de Vue (sucesora de Vuex). defineStore con una función de setup da la sintaxis de la Composition API — ref/computed son state/getters y las funciones devueltas son actions. El primer argumento es un id único de store. Los stores de setup son flexibles (puedes usar cualquier composable dentro). Alternativamente, usa la sintaxis Options (objeto state/getters/actions) para una sensación más tipo Vuex.

vue3
<!-- stores/counter.js -->
import { defineStore } from 'pinia'

// setup syntax (composition API style)
export const useCounterStore = defineStore('counter', () => {
  const count = ref(0)
  const double = computed(() => count.value * 2)

  function increment() {
    count.value++
  }

  function asyncIncrement() {
    setTimeout(() => count.value++, 1000)
  }

  return { count, double, increment, asyncIncrement }
})

Usar un store

Llama a useStore() dentro de setup para acceder a un store. Para la desestructuración reactiva, usa storeToRefs() (como toRefs pero se salta las actions). Las actions pueden desestructurarse directamente — están enlazadas al store. Pinia permite la mutación directa (counter.count = 5) y $patch para actualizaciones por lotes. Los stores son singletons — la misma instancia en la totalidad de los componentes. Instala Pinia con app.use(createPinia()).

vue3
<script setup>
import { useCounterStore } from '../stores/counter'
import { storeToRefs } from 'pinia'

const counter = useCounterStore()

// state and getters lose reactivity if destructured directly
// use storeToRefs to preserve it
const { count, double } = storeToRefs(counter)

// actions can be destructured directly (they're functions)
const { increment } = counter

// mutate state directly (Pinia allows it, unlike Vuex)
counter.count = 5
counter.$patch({ count: 10 })
counter.$patch(state => { state.count++ })
</script>

<template>
  <p>{{ count }} x 2 = {{ double }}</p>
  <button @click="increment">+</button>
</template>

Getters y composición de stores

Los getters son valores computados derivados del estado. Para usar otro store dentro de uno, simplemente llama a su useStore() — Pinia maneja la dependencia. Esto hace trivial componer stores (a diferencia de los módulos de Vuex). Los getters también pueden referenciar otros getters. Para operaciones asíncronas, simplemente escribe funciones async en el store — sin contexto especial de 'actions' como en Vuex.

vue3
<!-- stores/cart.js -->
import { defineStore } from 'pinia'
import { useUserStore } from './user'

export const useCartStore = defineStore('cart', () => {
  const items = ref([])

  // getter (computed)
  const total = computed(() =>
    items.value.reduce((sum, i) => sum + i.price * i.qty, 0)
  )

  const itemCount = computed(() =>
    items.value.reduce((n, i) => n + i.qty, 0)
  )

  // compose other stores
  const userStore = useUserStore()
  const canCheckout = computed(() =>
    userStore.isLoggedIn && items.value.length > 0
  )

  function addItem(item) {
    items.value.push(item)
  }

  return { items, total, itemCount, canCheckout, addItem }
})

Suscripciones y persistencia

$subscribe se dispara ante cualquier cambio de estado (con información de mutación y el nuevo estado). Úsalo para persistencia (localStorage, sessionStorage) o sincronizar con sistemas externos. $onAction se engancha a las llamadas de action — útil para logging, analítica o medir la duración de las actions. Los callbacks after/onError te dejan reaccionar a la finalización o al fallo de una action. La limpieza ocurre automáticamente al desmontar el componente.

vue3
<script setup>
import { useCartStore } from '../stores/cart'

const cart = useCartStore()

// subscribe to any state change
cart.$subscribe((mutation, state) => {
  console.log('cart changed', mutation.type, state)
  // persist to localStorage
  localStorage.setItem('cart', JSON.stringify(state.items))
})

// subscribe to actions
cart.$onAction(({ name, after, onError }) => {
  console.log('action started:', name)
  after(result => console.log('action done:', name, result))
  onError(err => console.error('action failed:', name, err))
})
</script>

Reset y módulos de store

Los stores de sintaxis Options tienen un $reset() integrado; los de setup no — implementa reset() manualmente reasignando cada ref. Pinia es modular por diseño — cada store es independiente, sin módulos anidados como Vuex. Compón stores llamando a useOtherStore() dentro de uno. Instala Pinia globalmente con createPinia(). Los stores son tree-shakeables y tienen excelente soporte de TypeScript e integración con devtools.

vue3
<!-- stores/user.js -->
import { defineStore } from 'pinia'

export const useUserStore = defineStore('user', () => {
  const name = ref('')
  const isLoggedIn = ref(false)

  function login(n) { name.value = n; isLoggedIn.value = true }
  function logout() { name.value = ''; isLoggedIn.value = false }

  // Pinia setup stores don't have a built-in $reset
  // implement it manually
  function reset() {
    name.value = ''
    isLoggedIn.value = false
  }

  return { name, isLoggedIn, login, logout, reset }
})

<!-- main.js -->
import { createPinia } from 'pinia'
const pinia = createPinia()
app.use(pinia)
20

Transiciones y animación

Componente Transition

Envuelve un elemento v-if/v-show en <Transition> para animar entrada/salida. Vue añade 6 clases en los momentos correctos: *-enter-from (estado inicial), *-enter-active (durante la transición), *-enter-to (estado final) y *-leave-*. Define transiciones/animaciones CSS sobre estas clases. La prop name reemplaza el prefijo 'v-'. Solo se permite un elemento hijo; para listas usa TransitionGroup.

vue3
<template>
  <Transition name="fade">
    <p v-if="show">Hello</p>
  </Transition>
</template>

<style>
/* 6 classes: {name}-enter-{from,active,to}, {name}-leave-{...} */
.fade-enter-active, .fade-leave-active {
  transition: opacity 0.3s ease;
}
.fade-enter-from, .fade-leave-to {
  opacity: 0;
}
</style>

Modos y hooks de Transition

mode='out-in' anima completamente la salida del elemento que sale antes de que empiece el que entra — perfecto para intercambiar componentes (pestañas) sin solape. mode='in-out' se usa rara vez. Los hooks de JavaScript (@before-enter, @enter, @leave) te permiten dirigir las animaciones con librerías como GSAP. Fja :css='false' para indicar a Vue que se salte la detección de CSS y confíe solo en tus hooks JS (ligera mejora de rendimiento).

vue3
<template>
  <!-- 'out-in': current leaves, then new enters -->
  <Transition mode="out-in" name="fade">
    <component :is="currentTab" />
  </Transition>

  <!-- JavaScript hooks for GSAP/anime.js -->
  <Transition
    @before-enter="beforeEnter"
    @enter="enter"
    @leave="leave"
    :css="false"
  >
    <div v-if="show">Animated</div>
  </Transition>
</template>

TransitionGroup para listas

TransitionGroup anima listas v-for con tres comportamientos: entrada (ítem nuevo), salida (ítem eliminado) y movimiento (ítem existente cambiando de posición). La clase *-move anima la técnica FLIP — Vue computa los deltas de posición y aplica una transición de transform. Fja position: absolute en leave-active para que el ítem que sale se retire del flujo, dejando que los hermanos se deslicen suavemente a su lugar.

vue3
<template>
  <TransitionGroup name="list" tag="ul">
    <li v-for="item in items" :key="item.id">{{ item.text }}</li>
  </TransitionGroup>
</template>

<style>
.list-enter-active, .list-leave-active { transition: all 0.5s; }
.list-enter-from, .list-leave-to { opacity: 0; transform: translateX(30px); }
/* the magic class for reordering */
.list-leave-active { position: absolute; }
.list-move { transition: transform 0.5s ease; }
</style>

Estado animado con envoltorio <Transition>

Puedes sobrescribir los nombres de clase por defecto de Vue con personalizados — enter-active-class y leave-active-class. Esto te permite enchufarte a sistemas de animación existentes (Animate.css, las utilidades de animación de Tailwind, keyframes personalizados). El patrón: define tu animación sobre una clase y apunta la transición de Vue hacia ella. Esto une el ciclo de vida de Vue con cualquier framework de animación CSS.

vue3
<template>
  <button @click="show = !show">Toggle</button>
  <Transition
    enter-active-class="animate__animated animate__fadeIn"
    leave-active-class="animate__animated animate__fadeOut"
  >
    <div v-if="show" class="box">Content</div>
  </Transition>
</template>

<!-- combine with third-party animation libraries -->
<!-- Animate.css, Tailwind animations, custom keyframes -->

Suspense para async

Suspense coordina el setup asíncrono — cuando un componente hijo usa await de nivel superior, se suspende y Suspense muestra el #fallback en su lugar. Una vez que cada hijo asíncrono se resuelve, se renderiza el slot por defecto. Es elegante para los componentes que piden datos. Ojo: Suspense sigue siendo experimental en Vue 3 — el manejo de errores exige onErrorCaptured. Para producción, la mayoría de equipos siguen usando composables + estado de carga.

vue3
<template>
  <Suspense>
    <template #default>
      <AsyncComponent />
    </template>
    <template #fallback>
      <div>Loading...</div>
    </template>
  </Suspense>
</template>

<!-- AsyncComponent uses top-level await -->
<script setup>
import { ref } from 'vue'
const data = ref(null)
// top-level await suspends the component
const res = await fetch('/api/data').then(r => r.json())
data.value = res
</script>
21

Teleport y Suspense

Fundamentos de Teleport

Teleport renderiza contenido a un elemento del DOM en otra parte del documento (a menudo a nivel de body), pero el componente conserva el contexto reactivo, props, emits, etc. de su padre. Esto resuelve los problemas de z-index/overflow con modals, tooltips y desplegables que quedarían recortados por overflow:hidden de los padres o contextos de apilamiento. El selector 'to' apunta al elemento de destino.

vue3
<!-- Modal.vue -->
<template>
  <!-- the rendered content is moved to #modals in the DOM,
       but keeps the component's reactive context -->
  <Teleport to="#modals">
    <div class="modal">
      <h2>{{ title }}</h2>
      <slot />
      <button @click="$emit('close')">Close</button>
    </div>
  </Teleport>
</template>

<!-- index.html must have -->
<!-- <div id="app"></div> -->
<!-- <div id="modals"></div> -->

Teleport condicional

La prop disabled te permite teleportar condicionalmente — cuando es true, el contenido se renderiza en el sitio (no teleportado). Es útil cuando el mismo componente se usa en contextos distintos (por ejemplo, un tooltip que debería teleportarse en un layout normal pero quedar en línea dentro de otro modal). Varios Teleports apuntando al mismo elemento se añaden en orden de renderizado. Teleport funciona con v-if dentro.

vue3
<template>
  <!-- disabled: render in place (not teleported) -->
  <Teleport :to="target" :disabled="inline">
    <div class="popup" v-if="show">...</div>
  </Teleport>
</template>

<script setup>
const props = defineProps({
  inline: Boolean  // if true, render inline instead of teleporting
})
const target = '#popups'
</script>

<!-- Multiple Teleports to same target: appended in order -->

Teleport para modals y notificaciones

Teleportar a body es el patrón estándar para los modals — el modal escapa cualquier restricción de overflow/transform/z-index del padre. Combínalo con Transition para la animación de entrada/salida. El @click.self en el backdrop cierra al hacer clic fuera (pero no sobre el contenido). Los slots permiten al padre personalizar por completo el header, body y footer del modal mientras el componente modal maneja el posicionamiento y la animación.

vue3
<!-- components/Modal.vue -->
<template>
  <Teleport to="body">
    <Transition name="modal">
      <div v-if="show" class="modal-backdrop" @click.self="$emit('close')">
        <div class="modal-content">
          <header><slot name="header" /></header>
          <slot />
          <footer><slot name="footer" /></footer>
        </div>
      </div>
    </Transition>
  </Teleport>
</template>

Suspense con setup asíncrono

Cuando el setup de un componente hijo usa await de nivel superior, devuelve una Promise. Suspense la atrapa y muestra #fallback hasta la resolución. El resultado del setup del componente suspendido se usa luego para el renderizado. Varios hijos asíncronos se coordinan — Suspense espera la totalidad. onErrorCaptured atrapa los errores de setup. Suspense sigue siendo experimental — para producción, prefiere el estado de carga manual en composables.

vue3
<!-- Parent.vue -->
<template>
  <Suspense>
    <AsyncProfile :id="userId" />
    <template #fallback>
      <Spinner />
    </template>
  </Suspense>
</template>

<!-- AsyncProfile.vue -->
<script setup>
const props = defineProps(['id'])
// top-level await suspends this component
const profile = await fetch(`/api/users/${props.id}`).then(r => r.json())
// component only renders after this resolves
</script>

Suspense anidado y componentes asíncronos

Suspense puede anidarse — cada nivel maneja su propia frontera asíncrona. El Suspense exterior muestra PageSkeleton mientras Dashboard (con la totalidad de sus dependencias) carga; el interior muestra ChartSkeleton específicamente para el gráfico. Esta carga granular mejora la UX: la carcasa de la página aparece primero y luego las secciones individuales se van llenando. Recuerda que Suspense es experimental — pruébalo a fondo y maneja los errores vía onErrorCaptured.

vue3
<template>
  <Suspense>
    <template #default>
      <Dashboard>
        <Suspense>
          <template #default>
            <AsyncChart :data="data" />
          </template>
          <template #fallback>
            <ChartSkeleton />
          </template>
        </Suspense>
      </Dashboard>
    </template>
    <template #fallback>
      <PageSkeleton />
    </template>
  </Suspense>
</template>
22

Provide / Inject

Provide e inject básicos

provide() hace que un valor esté disponible para cualquier componente descendiente; inject() lo recupera en cualquier punto inferior del árbol. Esto evita la perforación de props en componentes profundamente anidados. El segundo argumento de inject es un valor por defecto (usado si nada se proporciona). Las refs proporcionadas son reactivas — los descendientes pueden mutarlas y el padre ve los cambios. Usa claves Symbol para evitar colisiones en apps grandes.

vue3
<!-- Parent.vue -->
<script setup>
import { provide, ref } from 'vue'

const theme = ref('dark')
const user = ref({ name: 'Alice' })

// provide to all descendants
provide('theme', theme)
provide('user', user)
</script>

<!-- DeepChild.vue (any level of nesting) -->
<script setup>
import { inject } from 'vue'

const theme = inject('theme', 'light')  // default 'light'
const user = inject('user')

// these are reactive refs, just like in the parent
</script>

Estado proporcionado de solo lectura

Usa readonly() para exponer el estado sin permitir la mutación directa — los descendientes deben llamar a las funciones de action proporcionadas para cambiarlo. Este patrón (ref mutable privada + vista pública readonly + funciones de action) es una alternativa ligera a Pinia para el estado acotado al árbol de componentes. Impone el flujo de datos unidireccional y previene bugs por mutaciones aleatorias en lo profundo del árbol.

vue3
<!-- store.js (shared composable) -->
import { ref, readonly } from 'vue'

const _count = ref(0)  // private mutable state

export function useCountStore() {
  return {
    count: readonly(_count),  // consumers can't mutate
    increment: () => _count.value++  // only via action
  }
}

<!-- Provider.vue -->
<script setup>
import { provide } from 'vue'
import { useCountStore } from './store'

const store = useCountStore()
provide('countStore', store)
</script>

Claves de inyección tipadas

Usa InjectionKey<Ref<Tipo>> para crear una clave symbol tipada. Esto da inferencia completa de TypeScript — inject conoce el tipo de retorno. Las claves symbol evitan colisiones de cadena cuando varias librerías proporcionan valores. Para singletons de toda la app, prefiere Pinia sobre provide/inject — Pinia tiene devtools, persistencia y mejor testabilidad. Usa provide/inject para el contexto acotado al árbol de componentes (tema, formulario, locale).

vue3
<!-- keys.ts -->
import type { InjectionKey, Ref } from 'vue'
import { inject, provide } from 'vue'

export const ThemeKey: InjectionKey<Ref<string>> = Symbol('theme')

<!-- Provider.vue -->
<script setup>
import { ref } from 'vue'
import { ThemeKey } from './keys'

const theme = ref('dark')
provide(ThemeKey, theme)
</script>

<!-- Consumer.vue -->
<script setup>
import { inject } from 'vue'
import { ThemeKey } from './keys'

// TS knows theme is Ref<string> | undefined
const theme = inject(ThemeKey)
// with default
const theme2 = inject(ThemeKey, ref('light'))
</script>

Actualizar valores proporcionados

El patrón recomendado: proporciona un objeto que contenga el estado reactivo Y las funciones para mutarlo. Esto mantiene la API explícita y evita mutaciones aleatorias. Los hijos desestructuran el estado y las actions. Esto es esencialmente un mini-store — para algo más allá de unos pocos valores, considera un composable que devuelva la misma forma, o Pinia. El valor proporcionado es reactivo porque contiene una ref.

vue3
<!-- Provider.vue -->
<script setup>
import { ref, provide } from 'vue'

const count = ref(0)

// expose value + mutator together
provide('counter', {
  count,                       // reactive ref
  increment: () => count.value++,
  reset: () => count.value = 0
})
</script>

<!-- DeepChild.vue -->
<script setup>
import { inject } from 'vue'

const { count, increment, reset } = inject('counter')
// count is reactive, increment/reset are actions
</script>

<template>
  <p>{{ count }}</p>
  <button @click="increment">+</button>
  <button @click="reset">Reset</button>
</template>

Provide a nivel de app

app.provide() hace que un valor esté disponible para cada componente de la app — útil para constantes de toda la app (URLs de API, feature flags, configuración de entorno). A diferencia del provide a nivel de componente, esto no es reactivo por defecto (salvo que proporciones una ref). Es una buena forma de inyectar configuración específica del entorno sin importar archivos de env por todas partes. Combínalo con inject() en cualquier componente para acceder a estos globales.

vue3
<!-- main.js -->
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

// app-level provide — available to ALL components
app.provide('apiUrl', 'https://api.example.com')
app.provide('apiKey', import.meta.env.VITE_API_KEY)

// useful for app-wide constants
app.provide('features', {
  darkMode: true,
  beta: false
})

app.mount('#app')

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.