Teleport

Когда я впервые увидел Teleport во Vue 3, подумал: «Очередной способ запихнуть модалку в body». Но покопавшись глубже, понял — это гораздо интереснее. В реальных проектах Teleport решает задачи, с которыми обычные порталы в React или Angular справляются через костыли. Давайте разберемся, что в нём уникального и где новички (и не только) наступают на грабли.

Чем Teleport во Vue отличается от порталов в React и Angular

На первый взгляд — тот же механизм: рендерим компонент в другой части DOM. Но есть нюансы. В React портал — это способ «вырвать» дочерний элемент из иерархии, но контекст (провайдеры, стейт-менеджмент) остаётся в том же реакт-дереве. В Angular — это DomPortalOutlet, требующий явного управления жизненным циклом.

Teleport во Vue 3 работает иначе. Он не просто перемещает дом-узел — он перемещает виртуальное дерево компонента целиком. Это значит, что все директивы, слоты и реактивность остаются связанными с исходным родителем. Например, если внутри Teleport использовать v-if или v-for, они будут работать так, будто компонент всё ещё рядом — хотя физически он уже в .

Ещё важное отличие — Teleport во Vue не требует дополнительных врапперов. В React для портала нужен ReactDOM.createPortal(child, container), что добавляет абстракцию. Во Vue — просто . Минимум кода, максимум контроля.

Неочевидные сценарии использования Teleport (а не только модалки)

99% гайдов по Teleport показывают модальные окна и тултипы. Скучно. Реально полезные кейсы:

• Динамические хедеры и футеры. Когда у вас на странице фильтры, которые должны рендериться внутри блока контента (по дизайну), но логически принадлежат хедеру (чтобы сохранить стейт при скролле). Teleport элемента из контента в
  решает это без копирования пропсов.
• Параллельные тултипы с z-индексом. Частая боль — тултипы перекрываются друг другом, если они в разных контейнерах. Teleport все тултипы в один
  — и z-index работает предсказуемо.
• Рендеринг фрагментов страниц для A/B тестов. Можно телепортировать блок с вариантом B в другой контейнер без изменения основной вёрстки. Это мощно для экспериментов.
• Создание «плавающих» форм обратной связи, которые при скролле должны перемещаться, но не ломать layout родительской карточки.

Главные подводные камни: что не пишут в документации

Работаю с Teleport около года (а это уже 2026, инструмент стабилен). Вот на чём обожглись в нашей команде:

• SSR и гидратация. В серверном рендеринге Teleport по умолчанию не рендерится — тело пустое. Приходится ставить вокруг Teleport или использовать . Об этом забывают, потом на проде пустой попап.
• Анимированные модалки. Если вы используете внутри Teleport, анимация может глючить. Решение — ставить снаружи, а teleport делать внутри. Иначе переходы ломаются, потому что DOM уже телепортирован.
• Порядок монтирования. Teleport не гарантирует порядок, если несколько компонентов телепортируются в один контейнер. Например, два модальных окна — второе может нечаянно перезаписать первое. Нужно либо использовать очереди, либо рендерить по условию.
• Формы и их валидация. Если вы телепортируете элемент формы (скажем, кнопку) в другой контекст, атрибут form не срабатывает. Форма и кнопка физически в разных местах DOM — событие submit не привязывается. Приходится передавать id формы пропсом.

Советы профи: как использовать Teleport без багов

Первое — всегда указывайте disabled при определённых условиях. Например, для мобильной версии можно отключать телепорт, чтобы экономить ресурсы. Второе — не телепортируйте большие списки (тысячи элементов). Это создаёт нагрузку на DOM при каждом монтировании. Третье — используйте useTeleport из композаблов, если нужно более точечное управление. На практике часто бывает удобнее создать хук, который сам решает, телепортировать или нет.

Ещё один лайфхак: для тултипов я использую Teleport вместе с floating-ui. Это даёт идеальное позиционирование без переполнения родителя. И не забудьте про aria-labelledby — при телепортации доступность ломается, потому что DOM-дерево меняется. Явно прописывайте связи.

Заключение: стоит ли Teleport вашего внимания?

Однозначно да. Но — с оговорками. Если вы делаете SPA без SSR и не трогаете модалки — сахар приятный, но не критичный. Если ваш проект — сложная админка с оверлеями, тултипами, дропдаунами и кучей перекрывающихся элементов — Teleport сэкономит вам дни.

От других инструментов его отличает прозрачность: вы видите, куда улетает компонент, и можете это отладить через Devtools. В 2026 это особенно ценно, когда фреймворки всё больше абстрагируют реальность. Но помните: Teleport — это не серебряная пуля. Используйте его только тогда, когда без него layout ломается или z-index сходит с ума.

А если начнёте копипастить модалку из гайда — готовьтесь к неожиданностям на стыке анимаций и SSR.

Добавлено: 23.04.2026