Installation

Possible ways to install

NPM

This is the recommended way to install this Plugin.

Install with npm as a dependency:

npm i portal-vue

# or with yarn, respectively:
yarn add portal-vue
1
2
3
4

Then include the package in your application and install the plugin:

import PortalVue from 'portal-vue'

Vue.use(PortalVue)
1
2
3

CDN

PortalVue is available through a couple of CDNs, I recommend unpkg.com

Just include the script tag after the one of Vue.js

<script src="http://unpkg.com/vue/dist/vue.js"></script>
<script src="http://unpkg.com/portal-vue"></script>
1
2

The components will be named <portal> and <portal-target>, respectively.

TIP

PortalVue provides a UMD build (/dist/portal-vue.umd.min.js) which should be used in browsers, and which auto-installs itself when included via a script tag.

Unpkg and jsdelivr automatically give you this build. if you include it from another source, make sure to include the right one.

Nuxt Module

Hint

Only relevant for users of the Nuxt framework

First install from NPM, then add portal-vue/nuxt to modules section of nuxt.config.js

{
  modules: ['portal-vue/nuxt']
}
1
2
3

Options

When installing with Vue.use(), you can pass options to change the component names.

Vue.use(PortalVue, {
  portalName: 'my-portal', // default: 'portal'
  portalTargetName: 'my-target', // default:'portal-target'
})
1
2
3
4

These options would make the components available globally as <my-portal> and <my-target> respectively.

Using the components locally

If you don't want to register the components globally, don't do Vue.use('PortalVue')

Instead, import the component(s) in those components that you need them in and register them locally:

import { Portal, PortalTarget, MountingPortal } from 'portal-vue'

export default {
  components: {
    Portal,
    PortalTarget,
    MountingPortal,
  },
}
1
2
3
4
5
6
7
8
9

Builds

Portal-Vue ships in three different Builds.

Type File Usage
UMD (minified) portal-vue.umd.min.js To be included in a browser
UMD portal-vue.umd.js To be included in a browser. Non minified for debugging.
ESM portal-vue.esm.js For usage with bundlers that do support ESModules.
Commonjs portal-vue.common.js For usage with bundlers that don't support ESModule

Notes

UMD

When including Portal-vue from a CDN, make sure you get one of the of UMD builds.

About CDNs: unpkg.com and jsdelivr.com will load the umd lib automatically.

If you include it from other sources directly in your HTML, make sure to import portal-vue/dist/portal-vue.umd.min.js

Commonjs

This is the default main file of the package.

Webpack 1 doesn't support commonjs, neither do some dev tools, like jest doesn't either. So this is a sensible default to use.

ESM

Webpack >=2, rollup and parcel all can natively understand ESModules, so this is the best build to use with those bundlers.

The ESM version is marked as the default export of package.json for consumers that understand the "module" field in package.json (which is true for all the aforementioned bundlers), so doing import PortalVue from 'portal-vue' will automatically give you the ESM build if the bundler supports it.