Frontend · JavaScript · Vue.js

uni-app 5.14 Compiles Vue <teleport> Directly to Mini Program <root-portal>

By 前端毕业班 · Jul 6, 2026

Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Cross-platform Vue projects that target both H5 and Chinese mini programs can drop a whole class of conditional compilation. The unified syntax reduces template duplication and the bugs that come from maintaining parallel overlay strategies.

Summary

Writing a modal, drawer, or toast in a cross-platform Vue app used to require separate code paths: <teleport> for H5 and <root-portal> for mini programs. uni-app 5.14 removes that split. Developers write standard Vue <teleport to="body"> and the compiler transforms it into the platform's native <root-portal> at build time.

The transformation is a capability mapping, not a full polyfill. Mini program <root-portal> only elevates content to the page root; it cannot target arbitrary nodes the way Web Teleport can. Attributes that have no mini program equivalent, like `to` and `defer`, are silently dropped during compilation. The `disabled` prop is automatically negated to match <root-portal>'s inverted `enable` attribute.

Support currently covers WeChat, Alipay, and JD mini programs. H5 builds continue to use Vue's real <teleport> unchanged, so a single template now works across all targets without conditional compilation blocks.

Takeaways

— uni-app 5.14 compiles <teleport> into <root-portal> for WeChat, Alipay, and JD mini programs.

— Developers write standard Vue <teleport to="body"> once; the framework handles the platform-specific output.

— The `to` and `defer` props are removed during mini program compilation because <root-portal> does not support them.

— The `disabled` prop is automatically negated to <root-portal>'s `enable` prop at compile time.

— H5 builds still use Vue's native <teleport> with no change in behavior.

— This is a compile-time transformation, not a runtime simulation of Web Teleport inside the mini program.

Conclusions

Capability mapping rather than full simulation is a pragmatic choice: it avoids the performance and complexity cost of trying to replicate DOM-like behavior inside a mini program runtime that fundamentally lacks it.

The automatic negation of `disabled` to `enable` is a small but sharp detail — it prevents the common bug where a developer forgets to invert the boolean when switching between platforms.

Concepts & terms

root-portal

A WeChat mini program native component that renders its content at the page root level, outside the normal component tree, to avoid z-index and overflow clipping — similar in purpose to Vue's Teleport but without the ability to target arbitrary DOM nodes.

Teleport

A built-in Vue 3 component that renders its slot content into a specified DOM node outside the current component hierarchy, commonly used for modals, toasts, and overlays to escape CSS overflow and z-index constraints.

Source: juejin.cn ↗ Google Translate ↗ Backup ↗