Skip to content

Commit dfc68b8

Browse files
LinusBorgLinusBorg
committed
docs: added more documentation
1 parent 8bcfddb commit dfc68b8

File tree

1 file changed

+80
-41
lines changed

1 file changed

+80
-41
lines changed

‎package/README.md‎

Lines changed: 80 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
NOT PUBLISHED YET
44

5-
<!-- markdownlint-disable MD025 MD033 -->
5+
<!-- markdownlint-disable MD024 MD025 MD033 -->
66

77
## What this is
88

@@ -15,17 +15,6 @@ Its main usecase are components/elements that need to be positioned absolutely r
1515
* Alerts/notifications
1616
* Toasts
1717

18-
## Installation
19-
20-
> Since this package hasn't been published yet, this won't work.
21-
> It will be released soon.
22-
23-
```bash
24-
npm install -D @linusborg/vue-simple-portal
25-
# or
26-
yarn add -D @linusborg/vue-simple-portal
27-
```
28-
2918
## Usage
3019

3120
Minimal example:
@@ -47,7 +36,9 @@ Minimal example:
4736
template: `
4837
<div>
4938
<portal selector="#portal-target">
50-
<p>This will be mounted as a child element of <div id="portal-parget"> instead of somehwere inside the child tree of <div id="app">
39+
<p>This will be mounted as a child element
40+
of <div id="portal-parget"> instead of
41+
somewhere inside the child tree of <div id="app">
5142
</portal>
5243
<div>
5344
`
@@ -56,22 +47,7 @@ Minimal example:
5647
</body>
5748
```
5849

59-
Usage with a Bundler:
60-
61-
```javascript
62-
import Vue from 'vue'
63-
import Portal from '@linusborg/vue-simple-portal'
64-
import App from './App.vue'
65-
66-
Vue.use(Portal)
67-
68-
new Vue({
69-
el: '#app',
70-
render: h => h(App)
71-
})
72-
```
73-
74-
TODO: Insert jsfiddle
50+
<!-- TODO: Insert jsfiddle -->
7551

7652
## How this lib relates to `portal-vue`
7753

@@ -113,38 +89,41 @@ So I experimented a little and came up with this library here, which solves thes
11389

11490
### NPM / Yarn
11591

92+
> Since this package hasn't been published yet, this won't work.
93+
> It will be released soon.
94+
11695
```bash
117-
npm i -g vue-simple-portal
96+
npm install -D @linusborg/vue-simple-portal
11897
# or
119-
yarn add vue-simple-portal
98+
yarn add -D @linusborg/vue-simple-portal
12099
```
121100

122-
#### Install a a global plugin (Optional)
101+
#### Install as a global plugin (Optional)
123102

124103
This will make the `<portal>` component available globally, but also make the portal not lazy-loadable.
125104

126105
```javascript
127106
// main.js
128107
import Vue from 'vue'
129-
import VuePortal from 'vue-simple-portal'
108+
import VuePortal from '@inusborg/vue-simple-portal'
130109

131110
Vue.use(VuePortal, {
132-
name: 'portal' // optional, use to rename component
111+
name: 'portal', // optional, use to rename component
133112
})
134113
```
135114

136-
#### Or use and register it locally
115+
#### Or: Import and register it locally
137116

138117
```javascript
139118
// in a component definition
140-
import { Portal } from 'vue-simple-portal'
119+
import { Portal } from '@inusborg/vue-simple-portal'
141120
export default {
142121
name 'MyComponent',
143122
components: {
144123
Portal
145124
}
146125
}
147-
```
126+
````
148127

149128
### Browser
150129

@@ -159,10 +138,54 @@ Just include it with a script tag *after* Vue itself
159138

160139
The plugin will automatically register the `<portal>` component globally.
161140

162-
## Features
141+
## Props
163142

164143
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:
165144

145+
### `selector`
146+
147+
|type|required|default|
148+
|------|------|-------|
149+
|String|no | 'vue-portal-target-&lt;randomId&gt;' |
150+
151+
A query selector that defines the **target element** to which to append the content of the portal.
152+
153+
If no selector is given, a random default selector (created at startup) is used.
154+
155+
I no element matches the selector, a new element is created and appended to `<body>`
156+
157+
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.
158+
159+
### `disabled`
160+
161+
|type|required|default|
162+
|-----|-------|-------|
163+
|Boolean|no |false |
164+
165+
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.
166+
167+
### `prepend`
168+
169+
|type|required|default|
170+
|-----|-------|-------|
171+
|Boolean|no | false |
172+
173+
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.
174+
175+
Set the `prepend` prop if you want to *prepend* the content instead.
176+
177+
### `tag`
178+
179+
|type|required|default|
180+
|------|-------|------|
181+
|String|no |'DIV' |
182+
183+
When the content of `<poral>` 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.
184+
185+
The `tag` prop can be used to define what that element should be.
186+
187+
**Heads up**: When used in combination with `disabled`, it's used to define the root element of the `<portal>` itself!
188+
166189
## Caveats
167190
168191
Some caveats still exist, such as:
@@ -177,11 +200,11 @@ If you need to keep state between these switches, keep it in a [global state man
177200
178201
### Transitions
179202
180-
When you use a `<transition>` as the root element of the portal and then remove the portal (i.e. with `v-if`) or set `disabled` to `true`, no leave transition will happen.
203+
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.
181204
182-
This is to expected, as the same thing would happen if you removed a div that contains a `<transition>`, but often trips people up nonetheless.
205+
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.
183206

184-
If you need to remove or disable the portal *after* a transition has finished, you woulld have to work around this like this:
207+
If you need to remove or disable the portal *after* a transition has finished, you can make it work like this:
185208

186209
<details>
187210
<summary>Show Example</summary>
@@ -215,8 +238,24 @@ If you need to remove or disable the portal *after* a transition has finished, y
215238
</script>
216239
```
217240

241+
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.
242+
243+
As a last resort you can always use a Timeout if yu know the duration of the leave transition.
244+
218245
</details>
219246

247+
### Devtools
248+
249+
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.
250+
251+
### Target elements inside of your Vue app
252+
253+
The general advise 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](https://portal-vue.linusb.org) instead.
254+
255+
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.
256+
257+
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.
258+
220259
## Development
221260

222261
<details>

0 commit comments

Comments
 (0)