PortalVue is a Vue 3 component library that enables developers to render DOM elements outside of their natural component hierarchy, placing content anywhere in the document. The current stable version is 3.0.0, which targets Vue 3 and ships with full TypeScript types. While the project had a prolonged beta period, the 3.x line is now considered stable and actively maintained, receiving dependency updates and bug fixes as needed. Its primary differentiator is providing a robust, battle-tested solution for portal functionality directly within the Vue ecosystem, often used for modals, tooltips, and other overlay elements, without relying on imperative DOM manipulation. Vue 3 also offers its native `<Teleport>` component, which addresses many typical portal use cases, but PortalVue remains relevant for scenarios involving content movement between application components rather than simply moving to a specific DOM target.
npm install portal-vueVerified import paths — ran on the pinned version, not inferred.
Demonstrates a basic Vue 3 application using PortalVue to 'teleport' reactive content from one part of the component tree to a `PortalTarget` located elsewhere in the DOM.
Upgrade your project to Vue 3.x and update PortalVue to 3.x. Consult the official migration guide for detailed steps.
For single-source portals, consider using Vue 3's `<Teleport>`. For multiple sources, use `createPortalTarget()` as described in the PortalVue v3 documentation.
Refer to the migration guide for PortalVue 2.0.0 from older versions for `targetEl` alternatives, then apply the v3.x migration path if applicable.
Ensure your SSR strategy accounts for content that is 'portal-ed' by PortalVue appearing only client-side. See the dedicated SSR guide in the documentation.
Update transition implementations on `<PortalTarget>` to use the new `v-slot` based syntax, passing a transition to a slot named `wrapper` and using Vue's `<component :is="nodes[0]" />` to render the content.
Consult Vue 3's official documentation on `<Teleport>` to determine if it meets your requirements for simpler portal scenarios.
For Vue 3, `Vue.use()` is replaced by `app.use()`. Ensure you have a `createApp()` instance, e.g., `const app = createApp(App); app.use(PortalVue);`.
Ensure `app.use(PortalVue)` is called in your main application file before mounting your app, or import `{ Portal, PortalTarget } from 'portal-vue'` and register them locally in your components.Ensure you are on PortalVue 2.1.0+ (or 3.x) if using `Wormhole.hasContentFor()`. For older 2.x versions, a workaround using `!!Wormhole.transports[name].length` might be necessary, though this is not public API.
Review the PortalVue SSR documentation. During SSR, `<PortalTarget>` components must appear after their corresponding `<Portal>` components in the DOM. Consider dynamically rendering portal content client-side or using a custom target element.