diff --git a/src/guide/teleport.md b/src/guide/teleport.md
index b03ec2b9cd..6a94a44223 100644
--- a/src/guide/teleport.md
+++ b/src/guide/teleport.md
@@ -2,53 +2,95 @@
Vue encourages us to build our UIs by encapsulating UI and related behavior into components. We can nest them inside one another to build a tree that makes up an application UI.
-However, sometimes a part of a component's template belongs into this component logically, while from a technical point of view, it would be preferable to move this part of the template somewhere else in the DOM, outside of Vue app. For example, due to styling requirements, we want to move `
` from it's deeply nested position to the `
` with `id="endofbody"`
+However, sometimes a part of a component's template belongs to this component logically, while from a technical point of view, it would be preferable to move this part of the template somewhere else in the DOM, outside of the Vue app.
+
+A common scenario for this is creating a component that includes a full-screen modal. In most cases, you'd want the modal's logic to live within the component, but the positioning of the modal quickly becomes difficult to solve through CSS, or requires a change in component composition.
+
+Consider the following HTML structure.
```html
-
-
Move the #content with the portal component
+
+
Tooltips with Vue 3 Teleport
-
- This should be moved to #endofbody.
-
- This content should be nested
+
-
```
-To do so, we can use Vue's built-in `` component:
+Let's take a look at `modal-button`.
-```html
-
-
-
Move the #content with the portal component
-
-
-
- This should be moved to #endofbody.
-
-
- This content should be nested
+The component will have a `button` element to trigger the opening of the modal, and a `div` element with a class of `.modal`, which will contain the modal's content and a button to self-close.
+
+```js
+const app = Vue.createApp({});
+
+app.component('modal-button', {
+ template: `
+
+
+
+
+ I'm a modal!
+
+
-
-
-
+ `,
+ data() {
+ return {
+ modalOpen: false
+ }
+ }
+})
```
-As a result, we will have `teleport` content moved in the rendered DOM tree:
+When using this component inside the initial HTML structure, we can see a problem - the modal is being rendered inside the deeply nested `div` and the `position: absolute` of the modal takes the parent relatively positioned `div` as reference.
+
+Teleport provides a clean way to allow us to control under which parent in our DOM we want a piece of HTML to be rendered, without having to resort to global state or splitting this into two components.
+
+Let's modify our `modal-button` to use `` and tell Vue "**teleport** this HTML **to** the "**body**" tag".
-
- See the Pen
- Teleport by Vue (@Vue)
+```js
+app.component('modal-button', {
+ template: `
+
+
+
+
+
+ I'm a teleported modal!
+ (My parent is "body")
+
+
+
+
+ `,
+ data() {
+ return {
+ modalOpen: false
+ }
+ }
+})
+```
+
+As a result, once we click the button to open the modal, Vue will correctly render the modal's content as a child of the `body` tag.
+
+