vue-simple-portal
allows you to mount its slot content to the very end of the body element (or potentially any other DOM element on the page) as an immediate child.
Its main use case are components/elements that need to be positioned absolutely relative to the document/viewport, or fixed in some way or another, like:
Minimal example:
<body>
<script src="https://unpkg.com/vue/dist/vue.js"></script>
<script src="https://unpkg.com/@linusborg/vue-simple-portal"></script>
<div id="app">
<!-- your Vue app mounts to this element -->
</div>
<div id="portal-target">
<!-- our `<portal>` should move stuff here -->
</div>
<script>
new Vue({
el: '#app',
template: `
<div>
<portal selector="#portal-target">
<p>This will be mounted as a child element
of <div id="portal-target"> instead of
somewhere inside the child tree of <div id="app">
</portal>
</div>
`
})
</script>
</body>
portal-vue
I'm the author of portal-vue, a pretty popular portal library for Vue.js, so the obvious question is:
Why publish another Portal component?
Well, portal-vue
was my first successful library, and I wanted it to be awesome, so I packed it full of features to portal anything to anywhere, anytime you want.
That turned out pretty well, but also means the library is not exactly tiny anymore, and there also were a few issues that I found over time, so I wrote a smaller lib that addresses these issues while slimming down on features and (= bundle size) in order to concentrate on the main use case.
npm install -D @linusborg/vue-simple-portal
# or
yarn add -D @linusborg/vue-simple-portal
This will make the <portal>
component available globally, but also make the portal not lazy-loadable.
// main.js
import Vue from 'vue' // requires Vue >= 2.6
import VuePortal from '@linusborg/vue-simple-portal'
Vue.use(VuePortal, {
name: 'portal', // optional, use to rename component
})
// in a component definition
import { Portal } from '@linusborg/vue-simple-portal'
export default {
name 'MyComponent',
components: {
Portal
}
}
Just include it with a script tag after Vue itself
<head>
<script src="https://unpkg.com/vue/dist/vue.js"></script>
<script src="https://unpkg.com/vue-simple-portal"></script>
</head>
The plugin will automatically register the <portal>
component globally.
<portal>
works out of the box without setting any props. By default, it will:
<div>
with that id to the <body>
(once)<portal>
's slot content as a small, transparent component to that <div>
Which means the content is now an almost direct decendant of <body>
, and can safely and reliably be positioned absolutely etc.
So it's even easier than in the Usage Example from above:
<portal>
<p>This will be mounted as a child element
of the auto-generated <div> instead of
somewhere inside the child tree of <div id="app">
</portal>
As shown in the initial Usage Example, you can use the selector
prop to append to an element of your choosing.
If you are tired of specifying the selector over and over again, you can set it as the default selector, overwriting the randomly generated one:
Vue.use(VuePortal, {
selector: '#your-target',
})
If you don't want to install the plugin globally, you can use the setSelector
helper:
import { setSelector } from '@linusborg/vue-simple-portal'
setSelector('#your-target')
This library aims to do one thing only, and do it well: move stuff to the end of the document for things like modals. But it still gives the developer a few props to influence how exactly that happens:
selector
type | required | default |
---|---|---|
String | no | 'vue-portal-target-<randomId>' |
A query selector that defines the target element to which to append the content of the portal.
If no selector is given, a random default selector (created at startup) is used.
If no element matches the selector, a new element is created and appended to <body>
Consequently, this means that using the <portal>
without a selector
prop will always append to a div at the end of the <body>
element, which is a sensible default for the goal of this plugin.
disabled
type | required | default |
---|---|---|
Boolean | no | false |
When true
, renders the <portal>
's slot content in place instead of appending it to the target element. See Caveats section for a small footgun here.
prepend
type | required | default |
---|---|---|
Boolean | no | false |
Usually, the slot content of a portal will be appended to the target element, which means, if that element has child nodes, our content will be inserted as the last node in that list.
Set the prepend
prop if you want to prepend the content instead.
tag
type | required | default |
---|---|---|
String | no | 'DIV' |
When the content of <portal>
is appended to the target element, it's actually wrapped in a small, transparent component (for technical reasons). Like all (non-functional) components in Vue, it requires a single root element.
The tag
prop can be used to define what that element should be.
Heads up: When used in combination with disabled
, it's used to define the root element of the <portal>
itself!
Some caveats still exist, such as:
disabled
propWhen you toggle the disabled
prop from true
to false
or vice versa, any components inside of the portal will be destroyed in their current location and re-created in their new location.
This means all their local state is lost.
If you need to keep state between these switches, keep it in a global state manager
When you use a <transition>
as the root element of the portal and then remove the portal (i.e. with v-if
) or set its disabled
prop to true
, no leave transition will happen.
While this is to expected, as the same thing would happen if you removed a div that contains a <transition>
, it often trips people up, which is why it's mentioned here.
If you need to remove or disable the portal after a transition has finished, you can make it work like this:
If the slot content of the <portal>
contains components, they will show up as children of the <portal>
in the devtools, even though their root elements were mounted/moved to the target element, outside of the current component tree.
The general advice is to only mount to elements outside of your Vue app, as that's the prime use case of this library. If you need to mount to locations inside of your app, consider using portal-vue instead.
That being said, you can move content to an element that is controlled by Vue, i.e. is part of the template of some other component.
However, be advised that this element could be removed or replaced by Vue when that component re-renders, while the component instances bound to that element (or its children) are still in memory. This could potentialy be a memory leak if you're not careful.