Gathering detailed insights and metrics for @linusborg/vue-simple-portal
Gathering detailed insights and metrics for @linusborg/vue-simple-portal
A simpler Portal implementation focussed on moving slot content to the end of the body element
Installations
npm install @linusborg/vue-simple-portalDeveloper Guide
BETA
Typescript
No
Module System
CommonJS
Languages
3
JavaScript
Vue
HTML
JavaScript (97.38%)
Vue (2.43%)
HTML (0.18%)
Developer
linusborg
Download Statistics
Total Downloads
0
Last Day
0
Last Week
0
Last Month
0
Last Year
0
GitHub Statistics
NOASSERTION License
224 Stars
99 Commits
28 Forks
5 Watchers
20 Branches
11 Contributors
Updated on Oct 23, 2024
Maintainers
1
Package Meta Information
Latest Version
0.1.5
Package Id
@linusborg/vue-simple-portal@0.1.5
Size
10.88 kB
Published on
Jan 06, 2021
Total Downloads
Cumulative downloads
Total Downloads
NaN
Last Day
0%
NaN
Compared to previous day
Last Week
0%
NaN
Compared to previous week
Last Month
0%
NaN
Compared to previous month
Last Year
0%
NaN
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
vue-simple-portal
What this is
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:
- modals
- drodowns
- Alerts/notifications
- Toasts
Usage Example
Minimal example:
1<body> 2 <script src="https://unpkg.com/vue/dist/vue.js"></script> 3 <script src="https://unpkg.com/@linusborg/vue-simple-portal"></script> 4 <div id="app"> 5 <!-- your Vue app mounts to this element --> 6 </div> 7 8 <div id="portal-target"> 9 <!-- our `<portal>` should move stuff here --> 10 </div> 11 12 <script> 13 new Vue({ 14 el: '#app', 15 template: ` 16 <div> 17 <portal selector="#portal-target"> 18 <p>This will be mounted as a child element 19 of <div id="portal-target"> instead of 20 somewhere inside the child tree of <div id="app"> 21 </portal> 22 </div> 23 ` 24 }) 25 </script> 26</body>
How this lib relates to 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.
Click here if you want to know more
Drawbacks of portal-vue
- Useless Features: As far as I could tell, people didn't really use most of the features. For most people, this lib solved one problem: Moving stuff to the very end of the
<body>element so they could properly style and position their modals and similar components. For them, portal-vue comes with a lot of extra pounds that they don't need. - The approach that I chose to make the portal-ing work in all the different supported scenarios came with some caveats - the most severe being that it broke the
$parent <-> $childrenchain between the host component and the children that were moved. That also means a couple of things that rely on this chain internally don't work as expected, for example:provide/inject<route-view>
A solution to these drawbacks
So I experimented a little and came up with this library here, which solves these two things for the majority of users:
- It only does one thing, and does it well: It moves stuff to the end of the document. And it's much lighter for this reason.
- It keeps the
$parent <-> $childrenchain intact, so most of the existing caveats ofportal-vueare gone.
When to use which
- Use
vue-simple-portalwhen you want to move stuff to the end of the document only. - Use
portal-vuewhen you want to do more edge-case things, i.e. move stuff around to anywhere within your existing app, like the header component area, dynamically move the same content to different places by changing the destination prop etc.
Installation
NPM / Yarn
1npm install -D @linusborg/vue-simple-portal 2# or 3yarn add -D @linusborg/vue-simple-portal
Install as a global plugin (Optional)
This will make the <portal> component available globally, but also make the portal not lazy-loadable.
1// main.js 2import Vue from 'vue' // requires Vue >= 2.6 3import VuePortal from '@linusborg/vue-simple-portal' 4 5Vue.use(VuePortal, { 6 name: 'portal', // optional, use to rename component 7})
Or: Import and register it locally
1// in a component definition 2import { Portal } from '@linusborg/vue-simple-portal' 3export default { 4 name 'MyComponent', 5 components: { 6 Portal 7 } 8}
Browser
Just include it with a script tag after Vue itself
1<head> 2 <script src="https://unpkg.com/vue/dist/vue.js"></script> 3 <script src="https://unpkg.com/vue-simple-portal"></script> 4</head>
The plugin will automatically register the <portal> component globally.
Usage Notes
<portal> works out of the box without setting any props. By default, it will:
- Create a randomized id selector (once)
- Append a
<div>with that id to the<body>(once) - Append any
<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:
1<portal> 2 <p>This will be mounted as a child element 3 of the auto-generated <div> instead of 4 somewhere inside the child tree of <div id="app"> 5</portal>
Customizing the selector
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:
1Vue.use(VuePortal, { 2 selector: '#your-target', 3})
If you don't want to install the plugin globally, you can use the setSelector helper:
1import { setSelector } from '@linusborg/vue-simple-portal' 2setSelector('#your-target')
Props
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!
Caveats
Some caveats still exist, such as:
Losing local state when toggling disabled prop
When 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
Transitions
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:
Show Example
1<template> 2 <portal :disabled="disablePortal"> 3 <transition name="fade" appear @afterLeave="disablePortal = true"> 4 <div v-if="showTransitionContent"> 5 this will fade in/out 6 </div> 7 </transition> 8 </portal> 9</template> 10<script> 11 export default { 12 data: () => ({ 13 showTransitionContent: true, 14 disablePortal: false, 15 }), 16 methods: { 17 getOut() { 18 // calling this method will trigger the transition, 19 // which when finished, will disable the Portal 20 // through the `afterLeave` hook callback 21 this.showTransitionContent = false 22 23 } 24 } 25 } 26</script>
Of course this only works if you actually can listen to the events of the <transition>, and could be problematic or even impossible with 3rd-Party components, depending on their implementations.
As a last resort you can always use a Timeout if you know the duration of the leave transition.
Devtools
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.
Targeting elements inside of your Vue app
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.
Development
The following commands are useful for anyone forking this project and/or wanting to contribute
Project setup
1yarn install
Compiles and hot-reloads for development
1yarn run serve
Compiles and minifies for production
1yarn run build
Lints and fixes files
1yarn run lint
Run the tests
1yarn run test
Run your end-to-end tests
1yarn run test:e2e
Run your unit tests
1yarn run test:unit
Customize configuration
This project is based on Vue CLI, so see Configuration Reference of Vue CLI for further details.
No vulnerabilities found.
Reason
no binaries found in the repo
Reason
license file detected
Details
- Info: project has a license file: LICENCE:0
- Warn: project license file does not contain an FSF or OSI license.
Reason
Found 6/14 approved changesets -- score normalized to 4
Reason
0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
branch protection not enabled on development/release branches
Details
- Warn: branch protection not enabled for branch 'develop'
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
- Warn: 0 commits out of 22 are checked with a SAST tool
Reason
148 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-968p-4wvh-cqc8
- Warn: Project is vulnerable to: GHSA-67hx-6x53-jw92
- Warn: Project is vulnerable to: GHSA-v88g-cgmw-v5xw
- Warn: Project is vulnerable to: GHSA-whgm-jr23-g3j9
- Warn: Project is vulnerable to: GHSA-93q8-gq69-wqmw
- Warn: Project is vulnerable to: GHSA-fwr7-v2mv-hh25
- Warn: Project is vulnerable to: GHSA-qwcr-r2fm-qrc7
- Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw
- Warn: Project is vulnerable to: GHSA-cwfw-4gq5-mrqx
- Warn: Project is vulnerable to: GHSA-g95f-p29q-9xw4
- Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg
- Warn: Project is vulnerable to: GHSA-x9w5-v3q2-3rhw
- Warn: Project is vulnerable to: GHSA-w8qv-6jwh-64r5
- Warn: Project is vulnerable to: GHSA-257v-vj4p-3w2h
- Warn: Project is vulnerable to: GHSA-pxg6-pf52-xh8x
- Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275
- Warn: Project is vulnerable to: GHSA-gxpj-cx7g-858c
- Warn: Project is vulnerable to: GHSA-w573-4hg7-7wgq
- Warn: Project is vulnerable to: GHSA-3wcq-x3mq-6r9p
- Warn: Project is vulnerable to: GHSA-phwq-j96m-2c2q
- Warn: Project is vulnerable to: GHSA-ghr5-ch3p-vcr6
- Warn: Project is vulnerable to: GHSA-hvf8-h2qh-37m9
- Warn: Project is vulnerable to: GHSA-mpjm-v997-c4h4
- Warn: Project is vulnerable to: GHSA-3p22-ghq8-v749
- Warn: Project is vulnerable to: GHSA-77xc-hjv8-ww97
- Warn: Project is vulnerable to: GHSA-mq8j-3h7h-p8g7
- Warn: Project is vulnerable to: GHSA-p2jh-44qj-pf2v
- Warn: Project is vulnerable to: GHSA-p7v2-p9m8-qqg7
- Warn: Project is vulnerable to: GHSA-7x97-j373-85x5
- Warn: Project is vulnerable to: GHSA-7m48-wc93-9g85
- Warn: Project is vulnerable to: GHSA-qqvq-6xgj-jw8g
- Warn: Project is vulnerable to: GHSA-6r2x-8pq8-9489
- Warn: Project is vulnerable to: GHSA-r9p9-mrjm-926w
- Warn: Project is vulnerable to: GHSA-434g-2637-qmqr
- Warn: Project is vulnerable to: GHSA-49q7-c7j4-3p7m
- Warn: Project is vulnerable to: GHSA-977x-g7h5-7qgw
- Warn: Project is vulnerable to: GHSA-f7q4-pwc6-w24p
- Warn: Project is vulnerable to: GHSA-fc9h-whq2-v747
- Warn: Project is vulnerable to: GHSA-vjh7-7g9h-fjfh
- Warn: Project is vulnerable to: GHSA-j4f2-536g-r55m
- Warn: Project is vulnerable to: GHSA-r7qp-cfhv-p84w
- Warn: Project is vulnerable to: GHSA-6h5x-7c5m-7cr7
- Warn: Project is vulnerable to: GHSA-rv95-896h-c2vc
- Warn: Project is vulnerable to: GHSA-qw6h-vgh9-j6wx
- Warn: Project is vulnerable to: GHSA-74fj-2j2h-c42q
- Warn: Project is vulnerable to: GHSA-pw2r-vq6v-hr8c
- Warn: Project is vulnerable to: GHSA-jchw-25xp-jwwc
- Warn: Project is vulnerable to: GHSA-cxjh-pqwp-8mfp
- Warn: Project is vulnerable to: GHSA-ww39-953v-wcq6
- Warn: Project is vulnerable to: GHSA-pfrx-2q88-qq97
- Warn: Project is vulnerable to: GHSA-765h-qjxv-5f44
- Warn: Project is vulnerable to: GHSA-f2jv-r9rf-7988
- Warn: Project is vulnerable to: GHSA-vfrc-7r7c-w9mx
- Warn: Project is vulnerable to: GHSA-7wwv-vh3v-89cq
- Warn: Project is vulnerable to: GHSA-43f8-2h32-f4cj
- Warn: Project is vulnerable to: GHSA-pfq8-rq6v-vf5m
- Warn: Project is vulnerable to: GHSA-rc47-6667-2j5j
- Warn: Project is vulnerable to: GHSA-c7qv-q95q-8v27
- Warn: Project is vulnerable to: GHSA-78xj-cgh5-2h22
- Warn: Project is vulnerable to: GHSA-2p57-rm9w-gvfp
- Warn: Project is vulnerable to: GHSA-7r28-3m3f-r2pr
- Warn: Project is vulnerable to: GHSA-r8j5-h5cx-65gg
- Warn: Project is vulnerable to: GHSA-896r-f27r-55mw
- Warn: Project is vulnerable to: GHSA-9c47-m6qq-7p4h
- Warn: Project is vulnerable to: GHSA-76p3-8jx3-jpfq
- Warn: Project is vulnerable to: GHSA-3rfm-jhwj-7488
- Warn: Project is vulnerable to: GHSA-hhq3-ff78-jv3g
- Warn: Project is vulnerable to: GHSA-p6mc-m468-83gw
- Warn: Project is vulnerable to: GHSA-29mw-wpgm-hmr9
- Warn: Project is vulnerable to: GHSA-35jh-r3h4-6jhm
- Warn: Project is vulnerable to: GHSA-4wx3-54gh-9fr9
- Warn: Project is vulnerable to: GHSA-7wpw-2hjm-89gp
- Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv
- Warn: Project is vulnerable to: GHSA-f8q6-p94x-37v3
- Warn: Project is vulnerable to: GHSA-vh95-rmgr-6w4m
- Warn: Project is vulnerable to: GHSA-xvch-5gv4-984h
- Warn: Project is vulnerable to: GHSA-8hfj-j24r-96c4
- Warn: Project is vulnerable to: GHSA-wc69-rhjr-hc9g
- Warn: Project is vulnerable to: GHSA-qrpm-p2h7-hrv2
- Warn: Project is vulnerable to: GHSA-mwcw-c2x4-8c55
- Warn: Project is vulnerable to: GHSA-r683-j2x4-v87g
- Warn: Project is vulnerable to: GHSA-5rrq-pxf6-6jx5
- Warn: Project is vulnerable to: GHSA-8fr3-hfg3-gpgp
- Warn: Project is vulnerable to: GHSA-gf8q-jrpm-jvxq
- Warn: Project is vulnerable to: GHSA-2r2c-g63r-vccr
- Warn: Project is vulnerable to: GHSA-cfm4-qjh2-4765
- Warn: Project is vulnerable to: GHSA-x4jg-mjrx-434g
- Warn: Project is vulnerable to: GHSA-5fw9-fq32-wv5p
- Warn: Project is vulnerable to: GHSA-px4h-xg32-q955
- Warn: Project is vulnerable to: GHSA-rp65-9cf3-cjxr
- Warn: Project is vulnerable to: GHSA-6fx8-h7jm-663j
- Warn: Project is vulnerable to: GHSA-hj48-42vr-x3v9
- Warn: Project is vulnerable to: GHSA-9wv6-86v2-598j
- Warn: Project is vulnerable to: GHSA-rhx6-c78j-4q9w
- Warn: Project is vulnerable to: GHSA-h7cp-r72f-jxh6
- Warn: Project is vulnerable to: GHSA-v62p-rq8g-8h59
- Warn: Project is vulnerable to: GHSA-566m-qj78-rww5
- Warn: Project is vulnerable to: GHSA-7fh5-64p2-3v2j
- Warn: Project is vulnerable to: GHSA-hwj9-h5mp-3pm3
- Warn: Project is vulnerable to: GHSA-wvhm-4hhf-97x9
- Warn: Project is vulnerable to: GHSA-h4hr-7fg3-h35w
- Warn: Project is vulnerable to: GHSA-gj77-59wh-66hg
- Warn: Project is vulnerable to: GHSA-hqhp-5p83-hx96
- Warn: Project is vulnerable to: GHSA-3949-f494-cm99
- Warn: Project is vulnerable to: GHSA-x7hr-w5r2-h6wg
- Warn: Project is vulnerable to: GHSA-6fw4-hr69-g3rv
- Warn: Project is vulnerable to: GHSA-hrpp-h998-j3pp
- Warn: Project is vulnerable to: GHSA-5q6m-3h65-w53x
- Warn: Project is vulnerable to: GHSA-p8p7-x288-28g6
- Warn: Project is vulnerable to: GHSA-gcx4-mw62-g8wm
- Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw
- Warn: Project is vulnerable to: GHSA-m6fv-jmcg-4jfg
- Warn: Project is vulnerable to: GHSA-h9rv-jmmf-4pgx
- Warn: Project is vulnerable to: GHSA-hxcc-f52p-wc94
- Warn: Project is vulnerable to: GHSA-cm22-4g7w-348p
- Warn: Project is vulnerable to: GHSA-g4rg-993r-mgx7
- Warn: Project is vulnerable to: GHSA-4rq4-32rv-6wp6
- Warn: Project is vulnerable to: GHSA-64g7-mvw6-v9qj
- Warn: Project is vulnerable to: GHSA-3f95-r44v-8mrg
- Warn: Project is vulnerable to: GHSA-28xr-mwxg-3qc8
- Warn: Project is vulnerable to: GHSA-9p95-fxvg-qgq2
- Warn: Project is vulnerable to: GHSA-9w5j-4mwv-2wj8
- Warn: Project is vulnerable to: GHSA-25hc-qcg6-38wj
- Warn: Project is vulnerable to: GHSA-xfhh-g9f5-x4m4
- Warn: Project is vulnerable to: GHSA-qm95-pgcg-qqfq
- Warn: Project is vulnerable to: GHSA-cqmj-92xf-r6r9
- Warn: Project is vulnerable to: GHSA-vx3p-948g-6vhq
- Warn: Project is vulnerable to: GHSA-w5hq-hm5m-4548
- Warn: Project is vulnerable to: GHSA-4wf5-vphf-c2xc
- Warn: Project is vulnerable to: GHSA-jgrx-mgxx-jf9v
- Warn: Project is vulnerable to: GHSA-72xf-g2v4-qvf3
- Warn: Project is vulnerable to: GHSA-9m6j-fcg5-2442
- Warn: Project is vulnerable to: GHSA-hh27-ffr2-f2jc
- Warn: Project is vulnerable to: GHSA-rqff-837h-mm52
- Warn: Project is vulnerable to: GHSA-8v38-pw62-9cw2
- Warn: Project is vulnerable to: GHSA-hgjh-723h-mx2j
- Warn: Project is vulnerable to: GHSA-jf5r-8hm2-f872
- Warn: Project is vulnerable to: GHSA-5j4c-8p2g-v4jx
- Warn: Project is vulnerable to: GHSA-g3ch-rx76-35fx
- Warn: Project is vulnerable to: GHSA-wr3j-pwj9-hqq6
- Warn: Project is vulnerable to: GHSA-4v9v-hfq4-rm2v
- Warn: Project is vulnerable to: GHSA-9jgg-88mc-972h
- Warn: Project is vulnerable to: GHSA-j8xg-fqg3-53r7
- Warn: Project is vulnerable to: GHSA-6fc8-4gx4-v693
- Warn: Project is vulnerable to: GHSA-3h5v-q93c-6h6q
- Warn: Project is vulnerable to: GHSA-72mh-269x-7mh5
- Warn: Project is vulnerable to: GHSA-h4j5-c7cj-74xg
- Warn: Project is vulnerable to: GHSA-p9pc-299p-vxgp
Score
2.2
/10
Last Scanned on 2025-07-07
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More