In this article, we will dive into one of the cool new features that were introduced with Vue 3 - Teleport.

Want to learn how to use teleport with a free video lesson on Vue School?

What is Teleport?

While Vue 3 was under development and in beta version, teleport was known as portal.

Portal is a well-known concept from React that was also adopted in Vue 2 through third-party plugins like portal-vue. Its name suggests that it’s responsible for “teleporting” something from one to another place… and this is exactly what it does!

With teleport, you can render a component in a different place in the DOM tree, even if this place is not in your app's scope. Teleport is very handy when working with modals, notifications, popups or other elements that are sensitive to where they’re placed in the DOM tree.

Let me show you

<!-- UserCard.vue -->
<template>
  <div class="user-card">
    <b> {{ user.name }}</b>  
    <button @click="isPopUpOpen = true">Remove user</button>
    <div v-show="isPopUpOpen">
      <p>Are you sure?</p>
      <button @click="removeUser">Yes</button>
      <button @click="isPopUpOpen = false">No</button>
    </div>
  </div>
</template>

In the above code example we have a UserCard component that lets us remove a user from the database. After clicking the button, we will see a confirmation popup where we can confirm the action and remove the user with the removeUser method.

Keeping related components (the confirmation popup) in the same place is a good practice in terms of code maintenance. But when it comes to UI elements that should appear on top of the others, it can lead to some problems.

The first problem that we can encounter is the fact that the user-card class, as well as every other class higher in the DOM hierarchy, can affect the appearance of our popup. For example, if any of the containers have visibility: 0.5, the popup’s visibility will be affected.

Guaranteeing that our popup will appear on top of other components is another challenge. You can think about DOM elements as layers. We put those layers on top of each other to make a layout. Usually, when we want to cover some of the layers with other ones, we do this intentionally by either putting another element inside this layer or after it. One way of dealing with this issue is to use z-index CSS property to change the natural order of an element’s appearance, However, this method is not very elegant and usually gives us another challenge to deal with when we have multiple elements positioned with z-index

This is why we usually place UI elements that should appear on top of the other ones just before the closing </body> tag. This way we don’t need to do any hacks to be sure that our popup shows exactly where and how we want. It also ensures that other elements don't cover it.

So it looks like we have two conflicting good practices:

• The first one tells us to keep related components together, which implies keeping popup inside UserCard component
• The second tells us to put the popup right before the closing body tag.

To fulfill both requirements, we need to make sure that even though the popup code is located in the UserCard component, it will render somewhere else - ideally just before the closing body tag.

Thankfully this is precisely what teleport were made for!

Teleport in Vue 3

Among many of the new features, Vue 3 came with native support for teleport in the form of a Teleport component.

The good news is that the Teleport component is very simple! It has one property - to and a default slot. The slot content will render in the DOM element, that is selected by the query selector passed to the to prop.

<!-- In some nested Vue component -->
<NestedComponent>
  <Teleport to="#teleport-target">
    <PopUp />
  </Teleport>
</NestedComponent>
<!-- before closing body tag in index.html -->
<div id="teleport-target"></div>

In the above example, the PopUp component will render in the div with an id of teleport-target, even though it’s positioned inside NestedComponent.

Knowing this, we can rewrite our UserCard component into this form:

<!-- UserCard.vue -->
<template>
  <div class="user-card">
    <b> {{ user.name }}</b>  
    <button @click="isPopUpOpen = true">Remove user</button>
    <Teleport to="#teleport-target">
      <div v-show="isPopUpOpen">
        <p>Are you sure?</p>
        <button @click="removeUser">Yes</button>
        <button @click="isPopUpOpen = false">No</button>
      </div>
    </Teleport>
  </div>
</template>

Simple and easy, isn’t it? Now we can keep our code properly structured without being forced to do nasty workarounds to keep it working!

If you’re still curious and want to see other examples, here you can find a small website with a modal, using Vue 3 teleport. You can also browse test scenarios on vue-next repository.

Summary

Teleport is one of the nicest additions in Vue 3. It simplifies working with elements like modals and popups and makes it extremely easy to render it on top of their DOM elements without ugly workarounds.

Article written by Filip Rakowski

Web developer passionate about newest web technologies with special love for Vue and Progressive Web Apps. During my daily job I build open source products, interfaces for programmers and engage communities. Co-founder of Vue Storefront, author of StorefrontUI and Vue.js community partner.

• Tutorials