Teleports en Vue 3 para mover modales al DOM

Curso de Vue.js: Componentes y Composition API

Contenido del curso

Introducción

Built-in Components

Componentes personalizados

Composition API

Cierre del curso

23
Qué aprendiste en el curso de Vue.js 3
01:29 min

Tomar examen

Cursos Empresas Blog Live Conf Eventos Precios

0:0010:26

Teleports en Vue 3 para mover modales al DOM

Curso de Vue.js: Componentes y Composition API

Clase 7 de 23

Clase 7 / 23

Recursos

Los teleports en Vue.js son un componente nativo desde la versión 3 que te permite renderizar parte de un componente en otra ubicación del DOM, sin romper la estructura lógica de tu código. Esta funcionalidad resulta clave cuando construyes modales, tooltips o notificaciones que necesitan vivir al nivel del body aunque estén declarados dentro de un componente anidado.

Antes se conocían como portals en Vue 2 y no formaban parte del API oficial. Hoy son una herramienta lista para usar que mejora la organización del código y la experiencia de usuario.

Por qué necesitas teleports al construir un modal

Cuando creas un modal dentro de un single file component, Vue lo inserta en el lugar exacto donde lo declaraste en la jerarquía del DOM. El problema aparece cuando ese modal debe cubrir toda la pantalla: quedar atrapado dentro de un contenedor con overflow, z-index limitado o estilos heredados rompe la experiencia.

¿Qué hace exactamente un teleport en Vue.js? Mueve el contenido renderizado de un componente a otro nodo del DOM que tú indiques, manteniendo la lógica y el estado dentro del componente original.

La idea es simple: tu lógica vive en un componente reutilizable, pero el HTML final aparece donde realmente lo necesitas, normalmente al nivel del body.

Cómo crear un componente Modal.vue paso a paso

Dentro de la carpeta components se crea un archivo llamado Modal.vue. Por convención del ecosistema Vue.js, los nombres de archivo de componentes empiezan con mayúscula y usan camel case, lo que facilita su reconocimiento y autoimportación [3:00].

La estructura básica del template incluye:

Un div contenedor general.
Un button con el texto modal que dispara el evento @click="toggle".
Un div con clase modal que contiene título, párrafo y un botón de cerrar.
El segundo botón también ejecuta toggle para alternar la visibilidad.

En la sección <script> defines la función data() que retorna show: false y un método toggle que invierte el valor de show. Así controlas con un booleano cuándo se muestra el modal.

Cuál es la diferencia entre v-if y v-show

Para controlar la visibilidad del modal se usa la directiva v-show enlazada a la variable show. La diferencia con v-if es importante de entender.

¿Qué diferencia hay entre v-if y v-show? v-if agrega o elimina el elemento del DOM real, mientras que v-show lo mantiene siempre en el DOM y solo cambia su visibilidad con CSS (display: none).

Usar v-show es más eficiente cuando alternas la visibilidad con frecuencia, porque evita destruir y recrear el nodo cada vez.

Cómo aplicar teleport para mover el modal al body

Una vez que el modal funciona, al inspeccionarlo en el navegador verás que vive dentro de la jerarquía del componente padre. Para teleportarlo, envuelves el contenido que quieres mover dentro de la etiqueta <teleport> que Vue.js provee de forma nativa.

El atributo clave es to, que acepta cualquier selector CSS válido como destino. El ejemplo más común apunta directamente al body:

vue <teleport to="body">

<div class="modal" v-show="show"> <h2>Título</h2> <p>Contenido del modal</p> <button @click="toggle">Cerrar</button> </div> </teleport>

Al recargar el navegador notarás que en el lugar original aparecen dos comentarios: teleport start y teleport end. Estos marcadores indican dónde estaba declarado originalmente el componente, pero el HTML real se inyecta como último hijo del elemento destino [6:30].

Qué selectores puedo usar en el atributo to

El atributo to no se limita al body. Puedes usar cualquier pseudoselector de CSS válido: una clase como .modal-root, un id como #app-modals o cualquier selector que apunte a un nodo existente del DOM.

Esto te da flexibilidad para crear contenedores específicos donde montar tus componentes teleportados, lo que es útil cuando trabajas con librerías de terceros o frameworks de diseño que esperan estructuras específicas.

Ventajas de organizar tu código con teleports

El beneficio práctico va más allá de un modal funcional. Mantienes toda la lógica relacionada (estado, métodos, estilos, eventos) dentro de un único single file component, pero el resultado visual aparece en la ubicación correcta del DOM.

Algunos casos de uso típicos:

Modales y diálogos que cubren toda la pantalla.
Notificaciones tipo toast fijas en una esquina.
Tooltips que no deben heredar overflow del padre.
Menús contextuales que requieren posicionamiento absoluto global.

Además, ese archivo .vue es portable. Puedes compartirlo entre proyectos y tu modal seguirá funcionando con la misma lógica de teleport, sin importar la estructura del nuevo proyecto donde lo importes.

Si te animas a probarlo, cuéntame en los comentarios qué tipo de componentes piensas teleportar en tu próximo proyecto con Vue.js.