Teleport

Based on BrConfigProvider for global theme configuration, it supports DOM mount isolation, z-index management, and is an SSR-compatible enterprise-level Teleport component. It serves as the core dependency for BrDialog / BrModal.

Component Features

• 🧩 Flexible Mounting: Supports mounting to body, specified selectors, or HTMLElement. Automatically creates the target container if it doesn't exist.
• 📚 Z-Index Management: Automatically increments z-index for stacked instances. Supports global configuration via BrConfigProvider or fixed z-index values.
• 🛡️ Styling & Isolation: Built with TailwindCSS, supports optional style isolation (Shadow DOM / isolation).
• 🎬 Animations: Built-in mount/unmount animations (Fade, Zoom, Slide, etc.) with theme animation duration sync.
• 🖱️ Interaction Control: Built-in scroll lock and Escape key event listener based on the mounted container.

Basic Usage

The simplest way is to mount the content directly to the body.

Example

Custom Container

You can mount content to a specific node. If the target node doesn't exist, BrTeleport will automatically create it under the body.

Container #demo-teleport-target

Example

Multiple Instances Stacking

BrTeleport automatically manages the z-index of multiple instances, ensuring the last opened instance is on top. Pressing the ESC key only triggers the escape-key-down event on the topmost instance.

Example

Integration with BrDialog

As a core underlying component, BrTeleport can seamlessly integrate with advanced components like BrConfigProvider and BrDialog, automatically inheriting global theme configurations.

Example

Theme Customization

BrTeleport seamlessly integrates with BrConfigProvider, allowing global configuration of the z-index base and animation duration.

Example

API

BrTeleport Props

Property	Type	Default	Description
to	string | HTMLElement	'body'	Mount target, supports CSS selector or DOM node.
disabled	boolean	false	Disables teleport (renders in-place).
autoCreate	boolean	true	Automatically creates the target container if it doesn't exist.
isolation	boolean	false	Enables style isolation (adds isolation class).
zIndex	number	-	Fixed z-index value.
zIndexStrategy	'auto' | 'fixed' | 'config'	'auto'	z-index strategy: auto increment, fixed, or read from config.
animation	'fade' | 'zoom' | 'slide-up' | 'slide-down' | 'none'	'fade'	Mount/unmount transition animation type.
animationDuration	string	-	Custom animation duration (overrides global theme config).
lockScroll	boolean	false	Locks body scroll when mounted.
closeOnEscape	boolean	false	Triggers escape-key-down event on ESC key press.
lazy	boolean	false	Only renders content after mounting.

BrTeleport Emits

Event	Description	Callback Parameters
mount	Triggered when mounting completes	(container: HTMLElement)
unmount	Triggered when unmounting completes	-
escape-key-down	Triggered on ESC key press when closeOnEscape is true and instance is on top	(event: KeyboardEvent)

TeleportManager API

For manual z-index management, use the exported TeleportManager static class:

Method	Description
getZIndex(id: string, customZIndex?: number)	Allocates and returns a new z-index.
removeInstance(id: string)	Removes the specified mounted instance.
getTopInstance()	Gets the ID of the topmost instance.