5 | The content below this paragraph is rendered in the right/bottom (red)
6 | container by PortalVue
7 |
8 |
9 |
10 | This is content from the left/top container (green). The cool part is,
11 | it works across components, so you can send your content anywhere!
12 |
8 | The content below this paragraph is rendered in the right/bottom (red)
9 | container by PortalVue if the portal is actually rendered. When it's
10 | removed again, the content in the red panel will be removed as well.
11 |
12 |
13 |
14 | This is content from the left/top container (green).
15 |
7 | The content below this paragraph is rendered in the right/bottom (red)
8 | container by PortalVue if the portal is enabled. Otherwise, it's shown
9 | here in place.
10 |
11 |
12 |
13 | This is content from the left/top container (green).
14 |
89 | ```
90 |
91 | It has a counterpart of the same name on the `` component to pass props to the slot content when the `` is disabled.
92 |
93 | ## Slots API
94 |
95 | ### Default slot
96 |
97 | Any existing slot content is rendered in case that no content from any source Portal is available.
98 |
99 | Example:
100 |
101 | **Source**
102 |
103 |
104 | ```html {2}
105 |
106 |
This is rendered when no other content is available.
This is rendered when no other content is available.
139 | ```
140 |
141 | ### `wrapper`
142 |
143 | This slot can be used to define markup that should wrap the content received from a ``. This is usually only useful in combination with [`multiple`](#multiple), as for content from a single portal, you can just wrap the `` as a whole.
144 |
145 | The slot receives an array as its only prop, which contains the raw vnodes representing the content sent from the source portal(s).
146 |
147 | These vnodes can be rendered with Vue's dynamic component syntax:
148 |
149 | ``
150 |
151 | Example:
152 |
153 | **Source**
154 |
155 | ```html
156 |
157 |
158 |
159 |
160 |
161 | ```
162 |
163 | This slot is also useful to [add transitions (see advanced Guide)](../guide/advanced#transitions ).
164 | ## Events API
165 |
166 | ### `change`
167 |
168 | Emitted every time the component re-renders because the content from the `` changed.
169 |
170 | It receives an object with two properties:
171 |
172 | ```js
173 | {
174 | hasContent: boolean,
175 | sources: string[]
176 | }
177 | ```
178 |
179 | |Property| type | description|
180 | |----------|---------|-----------------------------------------------------------------------|
181 | |hasContent|boolean | indicated wether there is currently and content for the `PortalTarget`|
182 | |sources | string[]| Array with the names of the portal(s) that sent content |
183 |
184 |
185 | ```html {4}
186 |
187 |
188 |
189 |
190 |
199 | ```
200 |
--------------------------------------------------------------------------------
/docs/api/portal.md:
--------------------------------------------------------------------------------
1 | ---
2 | # sidebar: auto
3 | prev: false
4 | next: ./portal-target
5 | ---
6 |
7 | # Portal Component
8 |
9 | Wrap any content that you want to render somewhere else in a `Portal` component.
10 |
11 | ## Example usage
12 |
13 | ```html
14 |
19 |
This content will be sent through the portal
20 |
21 | ```
22 |
23 | ## Props API
24 |
25 | ### `disabled`
26 |
27 | | Type | Required | Default |
28 | | --------- | -------- | ------- |
29 | | `Boolean` | no | `false` |
30 |
31 | When `true`, the slot content will _not_ be sent through the portal to the defined PortalTarget.
32 |
33 | Instead, it will be rendered in place:
34 |
35 | **Source**
36 |
37 |
38 | ```html
39 |
40 |
49 | ```
50 |
51 | ::: tip Fragment
52 |
53 | `Portal` now renders a fragment, which means it doesn't render a root node around its content. Thats a new features supported in Vue 3, and pretty useful here - no superfluous wrapper element anymore!
54 |
55 | ::::
56 |
57 | ::: warning Local component state
58 |
59 | When toggling between enabled/disabled state, components in the portal slot are destroyed and re-created, which means any changes to their local state are lost.
60 |
61 | :::
62 | ### `name`
63 |
64 | | Type | Required | Default |
65 | | -------- | -------- | --------------- |
66 | | `String` | no | a random String |
67 |
68 | This optional prop can usually be left out, because `Portal` can generate a random string to provide an identifier for the source of the content being sent to the `PortalTarget`.
69 |
70 | But it might be a good idea to name your `Portal` components so you can debug them easier if need would be.
71 |
72 | ### `order`
73 |
74 | | Type | Required | Default |
75 | | -------- | -------- | ------- |
76 | | `Number` | no\* | 0 |
77 |
78 | This prop defines the order position in the output of the `PortalTarget`.
79 |
80 | ::: tip
81 | This prop is only useful when the Portal is sending content to a `PortalTarget` which has the `multiple` prop set.
82 | :::
83 |
84 | **Source**
85 |
86 |
87 | ```html
88 |
100 | ```
101 |
102 | ### `slotProps`
103 |
104 | | Type | Required | Default |
105 | | -------- | -------- | ------- |
106 | | `Object` | no | `{}` |
107 |
108 | This prop is only useful if:
109 |
110 | - the `disabled` prop is `true`, **and**
111 | - the `Portal`'s slot content is a [Scoped Slot](https://vuejs.org/v2/guide/components.html#Scoped-Slots).
112 |
113 | If that's the case, then the object you pass to `slotProps` is used to define the props that are passed to the scoped slot to display the content correctly in-place:
114 |
115 | It has a (more useful) counterpart in the `PortalTarget` component
116 |
117 | **Source**
118 |
119 |
120 | ```html
121 |
127 |
168 | ```
169 |
--------------------------------------------------------------------------------
/docs/examples._md:
--------------------------------------------------------------------------------
1 | ---
2 | sidebar: auto
3 | ---
4 |
5 | # Examples
6 |
7 | :::tip Call for Examples
8 | This section is pretty empty right now. It could need some more lovely examples.
9 |
10 | PRs are welcome :)
11 | :::
12 |
13 | ## Basic
14 |
15 | This is the starter example from the "Getting Started" page, demonstrating the basic usage.
16 |
17 |
18 |
19 | <<< @/docs/.vuepress/components/Examples/Basic.vue{8,17}
20 |
21 |
22 | ## Dynamic sidebar content
23 |
24 | By selectively rendering different `` components that all send to the same `` (but not at the same time), we can replace the ``'s content on demand, e.g. to put something into a sidebar area from teh main component:
25 |
26 | ::: warning Missing
27 | The example is still missing, haven't gotten around to migrating it from [this codepen of v1](https://codepen.io/LinusBorg/pen/xdQZqa)
28 | :::
29 |
30 | ## More to follow
31 |
32 | More examples will hopefully follow soon. Send me some suggestions!
33 |
--------------------------------------------------------------------------------
/docs/guide/SSR.md:
--------------------------------------------------------------------------------
1 | # Server-Side Rendering (SSR)
2 |
3 | When using [Vue's SSR capabilities](https://ssr.vuejs.org), portal-vue can't work reliably for a couple of reasons:
4 |
5 | 1. The internal Store (the "Wormhole") that's caching vnodes and connecting `` components to their `` counterparts, is a singleton. As such, changes to the Wormhole persist between requests, leading to all sorts of problems.
6 | 2. In SSR, Vue renders the page directly to a string, there are not reactive updates applied. Consequently, a `` appearing before a `` will render an empty div on the server whereas it will render the sent content on the client, resulting in a hydration vdom mismatch error, while a `` _following_ a `` would technically work.
7 |
8 | ## Solutions
9 |
10 | ### Disabling the portal on the server
11 |
12 | For the aforementioned reasons, starting with `2.1.2`, content won't be cached in the Wormhole anymore when on the server. Consequently, the HTML rendered by the server won't contain any DOM nodes in place of any ``
13 |
14 | ### Handling on the client
15 |
16 | We want to display the `` content on the client, though. In order to prevent any hydration mismatches, we can use a _really_ tiny [component called ``](https://github.com/egoist/vue-no-ssr), written by [@egoist](https://github.com/egoist), which can solve this problem.
17 |
18 | We wrap our `` elements in it, and it will prevent rendering on the server as well as on the client during hydration, preventing the error described above. Immediatly _after_ hyration, it will render the previously "hidden" content, so that the `` will render its content. Usually the user can hardly notice this as the update is near-immediate.
19 |
20 | Example:
21 |
22 | ```html
23 |
24 |
25 |
26 |
27 |
28 |
29 |
30 |
31 | ```
32 |
--------------------------------------------------------------------------------
/docs/guide/advanced.md:
--------------------------------------------------------------------------------
1 | ---
2 | # sidebar: auto
3 | prev: ./getting-started
4 | next: ./caveats
5 | ---
6 |
7 | # Advanced Usage
8 |
9 | ## Switching targets & sources
10 |
11 | The `to` prop of `` and the `name` prop of `` can be changed dynamically with `v-bind`, allowing you to send content of one `` to a different ``, or switch the source of a `` from one `` to another.
12 |
13 |
14 | ```html
15 |
16 | Content will be dynamically sent to the destination that `name` evaluates to
17 |
18 |
19 |
20 | by changing the 'name', you can define which portal's content should be shown.
21 |
22 | ```
23 | ## Scoped Slots
24 |
25 | PortalVue can also be used with [Scoped Slots](https://vuejs.org/v2/guide/components.html#Scoped-Slots)! This allows you to send a scoped slot to a PortalTarget, which can then provide props for the slot content:
26 |
27 |
28 | ```html
29 |
30 |
45 | ```
46 |
47 | ## Transitions
48 |
49 | ### Portal Transitions
50 |
51 | You can pass transitions to a `` without problems. It will behave just the same when the content is being rendered in the ``:
52 |
53 |
54 | ```html
55 |
56 |
57 |
You have {{messages.length}} new messages
58 |
No unread messages
59 |
60 |
61 | ```
62 |
63 | However, if you use a `` for multiple ``s, you likely want to define the transition on the target end instead. This is also supported.
64 | #### PortalTarget Transitions
65 |
66 |
67 | ```html
68 |
69 |
70 |
71 |
72 |
73 |
74 |
75 | ```
76 |
77 | Transitions for Targets underwent a redesign in PortalVue `3.0`. The new syntax is admittedly a bit more verbose and has a hack-ish feel to it, but it's a valid use of Vue's v-slot syntax and was necessary to get rid of some nasty edge cases with target Transitions that we had in PortalVue `2.*`.
78 |
79 | Basically, you pass a transition to a slot named `wrapper` and get an array called `nodes` from its slot props.
80 |
81 | You can the use Vue'S `` to turn those into the content of the transition.
82 |
83 | Here's a second example, using a `` instead:
84 |
85 |
86 | ```html
87 |
88 |
89 |
90 |
91 |
92 |
93 |
94 | ```
95 |
96 | ## Proper namespacing
97 |
98 | In order to move content from `Portals` to `PortalTargets`, some intermediary state management is required to coordinate between the two. We call this the "wormhole".
99 |
100 | In PortalVue `<=2.*`, this wormhole was a singleton instance, and as a consequence, the namespace for `to` and `name` properties was also global.
101 |
102 | In PortalVue `3.0` we still use a default wormhole, but now also support creating your own wormhole instance(s) and providing them to your portal components in different areas of your app - or different apps on the same page.
103 |
104 | This makes working with names a bit less prone to conflicts, especially when 3rd-party libraries that you are using in your projects also use portal-vue to move things around without you even knowing.
105 |
106 | So how does it work?
107 |
108 | TODO: properly document using `createWormhole()`
109 |
110 | ## Rendering outside of the Vue-App
111 |
112 | TODO: Introduce `createPortalTarget` and explain limited usage scenarios
113 |
--------------------------------------------------------------------------------
/docs/guide/caveats.md:
--------------------------------------------------------------------------------
1 | ---
2 | prev: ./advanced
3 | next: ./migration
4 | ---
5 |
6 | # Known Caveats
7 |
8 | Admittedly, portal-vue uses a little bit of trickery to do what it does. With this come some caveats, which are documented below.
9 |
10 | ## Local state lost when toggling `disabled`
11 |
12 | When toggling the `Portal` component's `disabled` state, components in the portal slot are destroyed and re-created, which means any changes to their local state are lost.
13 |
14 | If you need to persist state, use some sort of [state management](https://portal-vue-next-preview.netlify.com/)
15 |
16 | ## provide/inject
17 |
18 | Due to the way that Vue resolves provides from parent components, it will look for provided objects in the parent of `PortalTarget`, so any `provide`d objects of a parent of `Portal` will not be available to components within a portal - but it will have access to those provided by parents of the `PortalTarget`.
19 |
20 | Also, when using `multiple` portals sending content to one `PortalTarget`, it would be unclear which `Portal` component's injections should be used.
21 |
22 | ## `$parent`
23 |
24 | For the same reason, `this.$parent` will not give you the parent of the `Portal`, instead it will give you the `PortalTarget`, so code relying on `$parent` might break.
25 |
26 | ## [vue-router](https://router.vuejs.org)
27 |
28 | `RouterView` internally walks the $parent chain to find out how many (if any) parent `RouterView` components there are. Therefore `RouterView` inside a `Portal` will not be able to properly match its nested routes. See [#289](https://github.com/LinusBorg/portal-vue/issues/289) for discussion.
29 |
30 | ## `$refs`
31 |
32 | TODO: verify if this part about refs still applies as-is or needs changing.
33 |
34 | In rare cases, you might want to access a DOM element / component that is within the Portal content via a `ref`. This works, but sometimes requires a double `$nextTick`:
35 |
36 | ```javascript
37 | this.$nextTick().then(
38 | this.$nextTick(() => {
39 | this.$refs.yourRef // element should now be in the DOM.
40 | })
41 | )
42 | ```
43 |
44 | The reason is that depending on the scenario, it _can_ take one tick for the content to be sent to the Wormhole (the middleman between `Portal` and `PortalTarget`), and another one to be picked up by the `PortalTarget`.
45 |
--------------------------------------------------------------------------------
/docs/guide/getting-started.md:
--------------------------------------------------------------------------------
1 | ---
2 | # sidebar: auto
3 | prev: ./installation
4 | next: ./advanced
5 | ---
6 | # Getting Started with Portal-Vue
7 |
8 | ## What is PortalVue?
9 |
10 | PortalVue is a set of two components that allow you to render a component's template
11 | (or a part of it) anywhere in the document - even outside the part controlled by your Vue App!
12 |
13 | ::: tip What about Vue 3's `Teleport`?
14 | Good question! For most scenario's, you might not even need `portal-vue`, since the new `Teleport` component does it better than this library does (read: Without the [caveats](./caveats.md)).
15 |
16 | For an in-depth explanation, look [here](#)
17 | :::
18 |
19 | ## Setup
20 |
21 | Install Package:
22 |
23 | ```bash
24 | npm install --save portal-vue@next
25 |
26 | # or with yarn
27 | yarn add portal-vue@next
28 | ```
29 |
30 | Add it to your application:
31 |
32 | ```js
33 | import PortalVue from 'portal-vue'
34 | import { createApp } from 'vue'
35 | import App from './App.vue'
36 |
37 | const app = createApp(App)
38 |
39 | app.use(PortalVue)
40 |
41 | app.mount('#app')
42 | ```
43 |
44 | For more detailed installation instructions, additional options and installation via CDN,
45 | see the [Installation](./installation.md) section of the documentation.
46 |
47 | ## Browser Support
48 |
49 | This project is build for modern Javascript, sind Vue itself also targets modern browsers. It supports all browsers that also support ES Modules - those are:
50 |
51 | * Chrome >=61
52 | * Firefox >=60
53 | * Safari >=11
54 | * Edge >=16
55 |
56 | If you need to support older browsers for some reason, make sure to include `node_modules/portal-vue/dist` in the list of files that you transpile with babel.
57 |
58 | Vue CLI offers a dedicated option for this with [`transpileDependencies`](https://cli.vuejs.org/config/#transpiledependencies)
59 |
60 | ```js
61 | // vue.config.js
62 | module.exports = {
63 | transpileDependencies: ['portal-vue']
64 | }
65 | ```
66 |
67 | ## Usage
68 |
69 | :::tip About the examples
70 | The following examples contain live demos. When looking at them, keep in mind that for demo purposes, we move content around within one component, however in reality the `` can be positioned anywhere in your App.
71 |
72 | Also, the code of the Examples uses the Single-File-Component Format ("`.vue`" files). If you're not familiar with this, check out the official docs [here](https://vuejs.org/v2/guide/single-file-components.html).
73 | :::
74 |
75 | ### The Basics
76 |
77 |
78 | ```html
79 |
80 |
This slot content will be rendered wherever the
81 | with name 'destination'
82 | is located.
83 |
105 | This slot content will be rendered right here as long as the `disabled` prop
106 | evaluates to `true`,
107 | and will be rendered at the defined destination as when it is set to `false`
108 | (which is the default).
109 |
125 | When 'usePortal' evaluates to 'true', the portal's slot content will be
126 | rendered at the destination.
127 |
128 |
129 | When it evaluates to 'false', the content will be removed from the
130 | destination
131 |
132 |
133 |
134 | ```
135 |
136 |
140 |
141 | ### Multiple Portals, one Target
142 |
143 | The `PortalTarget` component has a `multiple` mode, which allows to render content from multiple `Portal` components _at the same time_.
144 |
145 | The order the content is rendered in can be adjusted through the `order` prop on the `Portal` components:
146 |
147 |
148 | ```html
149 |
150 |
169 | ```
170 |
171 |
179 |
180 | ## Use Cases
181 |
182 | ### Positioning Modals & Overlays
183 |
184 | In older browsers, `position: fixed` works unreliably when the element with that property is nested in a node tree that has other `position` values.
185 |
186 | But we normally need it to render components like modals, dialogs, notifications, snackbars and similar UI elements in a fixed position.
187 |
188 | Also, z-indices can be a problem when trying to render things on top of each other somewhere in the DOM.
189 |
190 | With PortalVue, you can render your modal/overlay/dropdown component to a `` that you can position as the very last in the page's `body`, making styling and positioning much easier and less error-prone.
191 |
192 | Now you can position your components with `position: absolute` instead
193 |
194 |
195 | ```html
196 |
197 |
198 |
199 |
200 |
201 | This overlay can be positioned absolutely very easily.
202 |
203 |
204 |
205 |
206 |
207 |
208 |
209 |
210 | ```
211 |
212 | ### Rendering dynamic widgets
213 |
214 | If you use Vue for small bits and pieces on your website, but want to render something in a location at the other end of the page, PortalVue got you covered.
215 |
216 | ### Tell us about your use case!
217 |
218 | We're sure you will find use cases beyond the ones we mentioned. If you do, please
219 | let us know by opening an issue on Github
220 | and we will include it here.
221 |
--------------------------------------------------------------------------------
/docs/guide/installation.md:
--------------------------------------------------------------------------------
1 | ---
2 | # sidebar: auto
3 | prev: false
4 | next: ./getting-started
5 | ---
6 |
7 | # Installation
8 |
9 | ## Possible ways to install
10 |
11 | ### NPM
12 |
13 | This is the recommended way to install this Plugin.
14 |
15 | Install with npm as a dependency:
16 |
17 | ```bash
18 | npm i portal-vue
19 |
20 | # or with yarn, respectively:
21 | yarn add portal-vue
22 | ```
23 |
24 | Then include the package in your application and install the plugin:
25 |
26 | ```javascript
27 | import PortalVue from 'portal-vue'
28 | import { createApp } from 'vue'
29 | import App from './App.vue'
30 |
31 | const app = createApp(App)
32 |
33 | app.use(PortalVue)
34 |
35 | app.mount('#app')
36 | ```
37 |
38 | ### CDN
39 |
40 | PortalVue is available through a couple of CDNs, I recommend
41 | unpkg.com
42 |
43 | Just include the script tag _after_ the one of Vue.js
44 |
45 | ```html
46 |
47 |
48 | ```
49 |
50 | The components will be named `` and ``, respectively.
51 |
52 | :::tip
53 | PortalVue provides a UMD [build](#builds) (`/dist/portal-vue.umd.min.js`) which should be used in browsers, and which auto-installs itself when included via a script tag.
54 |
55 | Unpkg and jsdelivr automatically give you this build. if you include it from another source, make sure to include the right one.
56 | :::
57 |
58 | ## Options
59 |
60 | When installing with `Vue.use()`, you can pass options to change the component names.
61 |
62 | ```javascript
63 | app.use(PortalVue, {
64 | portalName: 'my-portal', // default: 'portal'
65 | portalTargetName: 'my-target', // default:'portal-target'
66 | })
67 | ```
68 |
69 | These options would make the components available globally as `` and `` respectively.
70 |
71 | ## Using the components locally
72 |
73 | If you don't want to register the components globally, you can import the components locally. But you still need to isntall the plugin. just pass `false`for the component options:
74 |
75 | ```js
76 | app.use(PortalVue, {
77 | portalName: false,
78 | portalTargetName: false,
79 | })
80 | ```
81 |
82 | then import the component(s) in those components that you need them in and register them locally, which also allows to rename them:
83 |
84 | ```javascript
85 | import { Portal, PortalTarget } from 'portal-vue'
86 |
87 | export default {
88 | components: {
89 | MyPortal: Portal,
90 | PortalTarget,
91 | },
92 | }
93 | ```
94 |
95 | ## Typescript
96 |
97 | Portal-Vue 3 comes with full TS support. if you register the component globally, you need to tell your Vue IDE Extension (Volar) about them by adding a d.ts. file declaring these globally registered components:
98 |
99 | ```ts
100 | declare module 'vue' { // Vue 3
101 | export interface GlobalComponents {
102 | Portal: typeof import('portal-vue')['Portal']
103 | PortalTarget: typeof import('portal-vue')['PortalTarget']
104 | }
105 | }
106 |
107 | export {}
108 | ```
109 |
110 | Don't forget to `"include"` this file in your tsconfig.
111 | ## Custom Wormhole instance
112 |
113 | If you potentially have more than one Vue app on a page, you can avoid name conflicts by creating your own wormhole instance just for your app. This also means that your app can't send content to `PortalTarget` components in other apps running in the page, so it's probably an edge case.
114 |
115 | ```js
116 | import PortalVue, { createWormhole } from 'portal-vue'
117 | app.use(PortalVue, {
118 | wormhole: createWormhole()
119 | })
120 | ```
121 |
122 | ## Builds
123 |
124 | Portal-Vue ships in four different Builds.
125 |
126 | | Type | File | Usage |
127 | | -------------- | ----------------------- | -------------------------------------------------------- |
128 | | UMD (minified) | `portal-vue.umd.js` | To be included in a browser |
129 | | UMD | `portal-vue.umd.dev.js` | To be included in a browser. Non minified for debugging. |
130 | | ESM | `portal-vue.esm.mjs` | For usage with bundlers that _do_ support ESModules. |
131 |
132 | _Notes_
133 |
134 | ### UMD
135 |
136 | When including Portal-vue from a CDN, make sure you get one of the of UMD builds.
137 |
138 | **About CDNs**: `unpkg.com` and `jsdelivr.com` will load the umd lib automatically.
139 |
140 | If you include it from other sources directly in your HTML, make sure to import `portal-vue/dist/portal-vue.umd.min.js`
141 |
142 | ### ESM
143 |
144 | Webpack >=2, rollup, and parcel all can natively understand ESModules, so this is the best build to use with those bundlers.
145 |
146 | 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.
147 |
148 |
--------------------------------------------------------------------------------
/docs/guide/migration.md:
--------------------------------------------------------------------------------
1 | ---
2 | # sidebar: auto
3 | prev: ./caveats
4 | next: false
5 | ---
6 |
7 |
21 |
22 | ## Migrating from PortalVue 2
23 |
24 | PortalVue 3 is a complete re-write in order to optimize the codebase with new things Vue 3 gives us, and in the process, work over the APIs and features a bit, cleaning up some cruft here and there.
25 |
26 | From consumer's perspective, not too much has changed, so most use cases should just continue to work or need little adjusting to make them work again.
27 |
28 | One notable exception is ``, which was dropped in this release and is replaced with a small utility function to mount a `PortalTarget` for a normal `Portal` (see *Changes* further down.)
29 |
30 | ### Sidenotes: Vue 3 & Teleport
31 |
32 | One question developers already accustomed with Vue 3 will will likely have is:
33 |
34 | > "Do we actually still need this library? Vue 3 has `` now!"
35 |
36 | The honest answer is: You probably don't need this library anymore for the typical use cases like moving modals to `` etc. But if you are moving content _within_ your app, from one component to another, then `` on its own is not a good choice, and you will likely still profit from using this library.
37 |
38 | One thing to note here is that PortalVue still does **not** use ``under the hood. The main reason for that decision is that there would be a lot more behavioral differences that might make migration harder if we re-built PortalVue 3 on top of `Teleport`.
39 |
40 | So think of PortalVue 3 as a kind of Migration release that should give you more or less the same behavior you had with PortalVue 2 in you Vue 2 apps, but also comes with most of the caveats that the previous versions had.
41 |
42 | We do plan to release another major version later (maybe even as a new, separate library), which *will* be built in top of `Teleport`, at which point you can migrate to the new version in your Vue 3 app at your own pace if you want to.
43 |
44 | ## Migration Strategy
45 |
46 | The bread-and-butter use case should be fairly easy to migrate, as the `Portal` and `PortalTarget` Components only lost a couple of props that are now no longer required in Vue 3, like `slim` (see below).
47 |
48 | Notable breaking changes that do need some revamping affect two use cases:
49 |
50 | 1. Transitions defined on the `PortalTarget` side
51 | 2. Removal of `MountingPortal`, which is now better solved with `Teleport`, save for one edge case (`multiple` prop) for which we will cover a migration path further down.
52 |
53 | ## List of Changes
54 |
55 | ### Installation
56 |
57 | As the global API of creating a Vue app and registering Plugins changed a bit, you also need to adapt your Plugin installation a bit.
58 |
59 | See the chapter on [Installation](./installation.md) for further instructions.
60 | ### Portal Component
61 |
62 | #### `slim` prop removed
63 |
64 | In Vue 3, components no longer require a root element, so `slim` is no longer necessary. `Portal` will no longer render a root element, independent of the number of elements in its slot content.
65 |
66 | If you need a wrapping element, wrap `` in an element yourself:
67 |
68 | ```html
69 |
70 |
71 |
72 |
73 |
74 |
75 |
76 | ```
77 | ### PortalTarget Component
78 |
79 | #### `slim` prop removed
80 |
81 | In Vue 3, components no longer require a root element, so `slim` is no longer necessary. `Portal` will no longer render a root element, independent of the number of elements in its slot content.
82 |
83 | If you need a wrapping element, wrap `` in an element yourself:
84 |
85 | ```html
86 |
87 |
88 |
89 |
90 |
91 |
92 |
93 | ```
94 |
95 | #### New: `v-slot:wrapper`
96 |
97 | You can now pass an additional named slot to `PortalTarget` that can be used to wrap the contents coming from multiple `Portal` in markup individually:
98 |
99 | ```html
100 |
101 |
102 |
103 |
104 |
105 |
106 |
107 |
108 | ```
109 |
110 | See: [PortalTarget API: Wrapper slot](../api/portal-target.md#wrapper)
111 |
112 | #### `transition`, `transition-events` props removed.
113 |
114 | Instead of these props, you can now use the new `v-slot:wrapper` to wrap content in `` or `` components. [See the docs for more info here](./advanced.md#portaltarget-transitions)
115 |
116 | ### Removed: MountingPortal
117 |
118 | This component was removed. Depending on your use case, you have two alternative migration paths:
119 |
120 | 1. You move content from one `Portal` only: Use Vue's own `Teleport` instead ([Teleport docs](https://v3.vuejs.org/api/built-in-components.html#teleport))
121 | 2. You want to move content from multiple Places to the same mounted Portal: use `createPortalTarget()` utility function:
122 |
123 | ```html
124 |
125 |
126 |
This is the content to move
127 |
128 |
129 |
130 |
143 | ```
144 |
145 | In practice, you would likely call this function somewhere more global once, so that all other `Portal`components can move content this single `PortalTarget`.
146 |
147 |
148 |
149 | ### Wormhole
150 |
151 | The wormhole is the connecting "store" between the `Portal` and `PortalTarget` components. in PortalVue 2, it was a singleton, which meant that all apps and libraries on one page shared the same namespace for `to=""` names.
152 |
153 | PortalVue 3 still provides a default instance to all components in an app when installing the plugin, but now you can optionally create your own instance and use that instead of the default one.
154 |
155 | [Read more here](./installation.md#custom-wormhole-instance)
156 |
157 |
158 | ### Testing
--------------------------------------------------------------------------------
/docs/guide/portal-vue-teleport.md:
--------------------------------------------------------------------------------
1 | # PortalVue vs. ``
2 |
3 | TODO: write comparison between portal-vue and teleport
--------------------------------------------------------------------------------
/docs/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | sidebar: false
3 | outline: false
4 | ---
5 |
6 |
7 |
8 |
9 | ## Usage example
10 |
11 | ```html
12 |
13 |
This slot content will be rendered wherever the
14 | with name 'destination'
15 | is located.
16 |
8 | This page has two sub-routes, "Page A" and "Page B". Both of the routes
9 | have a portal that will teleport the title of the sub-route to the header
10 | on the parent route. If neither sub-route is active, it uses the default
11 | title.
12 |
13 |
This allows sub-routes to set page elements in parent routes.
26 | This content was created with a scoped Slot.
27 | When Portal is disabled, this paragraph is rendered in the left
28 | box.
29 | When it's enabled, it's rendered in the right box.
30 |
This is the content source. The portal is defined below.
4 |
5 | This Content was defined on the left,
6 | and transferred to this target on the right.
7 | Timestamp updates on each switch:
8 | {{ getTimeStamp() }}
9 |
10 |
5 | It was created in the component on the right, and transfered here with
6 | VuePortal.
7 | Click the "x" to remove links - all vue directives continue to work
8 | in their original context. Hint: When the source component is
9 | removed, then the target's content below disappears as well.
10 |
5 | Normally, they would be rendered below the input, but with VuePortal we
6 | can render them outside of this component, into the componenton the left
7 | in this case.
8 |
8 | 
13 |
14 |