r-teleport Directive

Move a subtree to a target selector while preserving its original binding context.

The r-teleport directive in Regor is a straightforward directive that empowers you to move an element anywhere within your document's DOM structure. This can be especially useful when you need to dynamically relocate elements to different parts of your web page.

r-teleportDOM utilities

Move a subtree to a target selector while preserving its original binding context.

Try it live

Move the DOM, keep the contextLive Regor

Live preview

Message in the source context

SOURCE / DECLARED HERE

The message's template starts in this region.

TARGET / RENDERED HERE

Still bound to the source context.

The element moves to the target. Its bindings still read the source context.

teleport.ts

import { html, ref } from 'regor'

export function createTeleport(interactive = false) {
  const active = ref(true)
  return {
    interactive,
    active,
    message: ref('Still bound to the source context.'),
    toggle: () => active(!active()),
  }
}

export const teleportTemplate = html` <div class="guide-demo">
  <div class="guide-controls">
    <label for="portal-message">Message in the source context</label
    ><input
      id="portal-message"
      type="text"
      maxlength="80"
      r-model="message"
      :value="message"
      :disabled="!interactive"
    /><button type="button" @click="toggle" :disabled="!interactive">
      {{ active ? 'Unmount message' : 'Mount message' }}
    </button>
  </div>
  <div class="directive-zones">
    <section class="directive-card">
      <span class="guide-kicker">SOURCE / DECLARED HERE</span>
      <p>The message's template starts in this region.</p>
      <div
        r-if="active"
        class="directive-portal-message"
        r-teleport="#directive-portal"
      >
        <strong>{{ message }}</strong>
      </div>
    </section>
    <section class="directive-card">
      <span class="guide-kicker">TARGET / RENDERED HERE</span>
      <div id="directive-portal"></div>
    </section>
  </div>
  <p class="guide-hint">
    The element moves to the target. Its bindings still read the source context.
  </p>
</div>`

browser.ts

import { createApp, useScope } from 'regor'
import { directiveExamples } from './examples'

const element = document.getElementById('directive-demo')
const name = element?.dataset.example
if (element && name && Object.hasOwn(directiveExamples, name)) {
  const example = directiveExamples[name as keyof typeof directiveExamples]
  createApp<object>(
    useScope<object>(() => example.create(true)),
    { element, template: example.template },
  )
}

Edit the source message. It renders in the target region, and unmounting removes it there too.

Usage

To utilize the r-teleport directive, follow this basic syntax:

<element r-teleport="targetSelector"></element>

element: The HTML element you wish to teleport/move.
targetSelector: A selector indicating the destination where you want to place the element.

Example

Here's an example of how you can employ the r-teleport directive:

<!-- Move the element with the 'my-element' ID to the element with the 'destination' ID -->
<div r-teleport="#destination">
  <div id="my-element">This element will be teleported.</div>
</div>

In this example, the outer <div> and its contents move under the element with ID destination. Their bindings continue to read the original context.

The target must exist

Use a selector that resolves to the intended destination. Moving the DOM does not change which context its bindings read.

Notes

The r-teleport directive allows you to dynamically reposition elements within the DOM structure, enhancing flexibility and interactivity in your web applications.
It works by selecting a target element based on a CSS selector (targetSelector) and moving the element to that location in the document.
This directive can be particularly handy for creating dynamic UIs and interactive web pages.
You can use this directive in combination with other Regor directives and features to create rich and dynamic web applications.

Try it live

Usage

Example

Notes

See Also