1 1
# Visible
2 2 3 -
> The `v-b-visible` directive allows you to react when an element becomes visible in the viewport.
3 +
> `v-b-visible` is a lightweight directive that allows you to react when an element becomes visible
4 +
> in the viewport and/or when it moves out of the viewport (or is no longer visible).
4 5 5 6
The `v-b-visible` directive was added in version `2.1.0`.
6 7 7 8
## Overview
8 9 9 10
- `v-b-visible` will call your callback method with a boolean value indicating if the element is
10 -
visible (intersecting) with the viewport.
11 +
visible (intersecting with the viewport) or not.
11 12
- The directive can be placed on almost any element or component.
12 -
- Changes in visibility cqn also be detected (such as `display: none`), as long as the element is
13 -
within (or partially within) the viewport, or within the optional offset.
14 -
- Several BootstrapVue components use `v-b-visible`, such as `<b-img-lazy>`.
13 +
- Changes in visibility can also be detected (such as `display: none`), as long as the element is
14 +
within (or partially within) the viewport, or within the optional offset. Note: transitioning to a
15 +
non-visible state due to `v-if="false"` _cannot_ be detected.
16 +
- Internally, BootstrapVue uses this directive in several components, such as `<b-img-lazy>`.
15 17
- The `v-b-visible` directive requires browser support of
16 18
[`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).
17 19
For older browsers that do not support `IntersectionObserver`, you will need to use a
18 20
[polyfill](/docs/#js).
21 +
- If `IntersectionObserver` support is not detected, then `v-b-visible` will assume the element is
22 +
_always visible_, and will call the callback once with the argument set to `true`.
19 23 20 24
## Directive syntax and usage
21 25 22 26
```html
23 -
<div v-b-visible.[mod].[...]="callback">content</div>
27 +
<div v-b-visible.[mod1].[mod2]="callback">content</div>
24 28
```
25 29 26 30
Where `callback` is required:
27 31 28 32
- A function reference that will be called whenever visibility changes. The callback is passed a
29 33
single boolean argument. `true` indicates that the element is intersecting (partially or entirely
30 34
visible) in the viewport, or `false` if the element is not visible/intersecting with the viewport.
31 -
The callback will be called each time the element's visibility changes (except when hte `once`
35 +
The callback will be called each time the element's visibility changes (except when the `once`
32 36
modifier is used. See below for details)
33 37 34 -
Where `[mod]` can be (all optional):
38 +
Where `[mod1]` or `[mod2]` can be (all optional):
35 39 36 -
- A positive number representing the offset (margin) in pixels _away_ from the edge of the viewport
37 -
to determine when the element is considered in (or just about to be in) the viewport. The value
38 -
adds a margin around the view port. The default value is `0`.
39 -
- The keyword `once`. When this modifier is present, the callback will be called once (with the
40 -
argument of `true` indicating the element is intersecting/visible) when the element is
41 -
intersecting with the viewport. Note the callback may be called prior to this with an argument of
42 -
`false` signifying the element is not intersecting/visible.
40 +
- A positive integer number representing the offset (margin) in pixels _away_ from the edge of the
41 +
_viewport_ to determine when the element is considered in (or just about to be in) the viewport.
42 +
The value adds a margin around the viewport. The default value is `0`.
43 +
- The keyword `once`. When this modifier is present, the callback will be called only once the first
44 +
time the element is visible (with the argument of `true` indicating the element is
45 +
intersecting/visible). Note the callback _may be_ called prior to this with an argument of `false`
46 +
signifying the element is not intersecting/visible.
43 47 44 -
### Usage examples
48 +
The order of the modifiers is not important.
45 49 46 -
Basic:
50 +
### Usage syntax examples
51 + 52 +
In all use cases, the callback function is required.
53 + 54 +
#### Basic (no modifiers)
47 55 48 56
```html
49 57
<template>
@@ -64,8 +72,10 @@ export default {
64 72
</script>
65 73
```
66 74 67 -
With viewport offset modifier of 350px (if the element is outside of the physical viewport by at
68 -
least 350px, then it will be considered "visible"):
75 +
#### With viewport offset modifier
76 + 77 +
In this example, the modifier value represents 350px (if the element is outside of the physical
78 +
viewport by at least 350px, then it will be considered "visible"):
69 79 70 80
```html
71 81
<template>
@@ -86,7 +96,7 @@ export default {
86 96
</script>
87 97
```
88 98 89 -
With `once` modifier:
99 +
#### With the `once` modifier
90 100 91 101
```html
92 102
<template>
@@ -110,7 +120,7 @@ export default {
110 120
</script>
111 121
```
112 122 113 -
With `once` and offset modifiers:
123 +
#### With both `once` and offset modifiers
114 124 115 125
```html
116 126
<template>
@@ -133,3 +143,98 @@ export default {
133 143
}
134 144
</script>
135 145
```
146 + 147 +
## Live examples
148 + 149 +
Here are two live examples showing two common use cases.
150 + 151 +
### Visibility of scrolled content
152 + 153 +
Scroll the container to see the reaction when the `<b-badge>` scrolls into view:
154 + 155 +
```html
156 +
<template>
157 +
<div>
158 +
<div
159 +
:class="[isVisible ? 'bg-info' : 'bg-light', 'border', 'p-2', 'text-center']"
160 +
style="height: 85px; overflow-y: scroll;"
161 +
>
162 +
<p>{{ text }}</p>
163 +
<b-badge v-b-visible="handleVisibility">Element with v-b-visible directive</b-badge>
164 +
<p>{{ text }}</p>
165 +
</div>
166 +
<p class="mt-2">
167 +
Visible: {{ isVisible }}
168 +
</p>
169 +
</div>
170 +
</template>
171 + 172 +
<script>
173 +
export default {
174 +
data() {
175 +
return {
176 +
isVisible: false,
177 +
text: `
178 +
Quis magna Lorem anim amet ipsum do mollit sit cillum voluptate ex nulla
179 +
tempor. Laborum consequat non elit enim exercitation cillum aliqua
180 +
consequat id aliqua. Esse ex consectetur mollit voluptate est in duis
181 +
laboris ad sit ipsum anim Lorem. Incididunt veniam velit elit elit veniam
182 +
Lorem aliqua quis ullamco deserunt sit enim elit aliqua esse irure. Laborum
183 +
nisi sit est tempor laborum mollit labore officia laborum excepteur commodo
184 +
non commodo dolor excepteur commodo. Ipsum fugiat ex est consectetur ipsum
185 +
commodo tempor sunt in proident. Non elixir food exorcism nacho tequila tasty.
186 +
`
187 +
}
188 +
},
189 +
methods: {
190 +
handleVisibility(isVisible) {
191 +
this.isVisible = isVisible
192 +
}
193 +
}
194 +
}
195 +
</script>
196 + 197 +
<!-- v-b-visible-scroll.vue -->
198 +
```
199 + 200 +
### CSS display visibility detection
201 + 202 +
Click the button to change the `<div>` visibility state:
203 + 204 +
```html
205 +
<template>
206 +
<div>
207 +
<b-button @click="show = !show" class="mb-2">Toggle display</b-button>
208 +
<p>Visible: {{ isVisible }}</p>
209 +
<div class="border p-3" style="height: 6em;">
210 +
<!-- We use Vue's `v-show` directive to control the CSS `display` of the div -->
211 +
<div v-show="show" class="bg-info p-3">
212 +
<b-badge v-b-visible="handleVisibility">Element with v-b-visible directive</b-badge>
213 +
</div>
214 +
</div>
215 +
</div>
216 +
</template>
217 + 218 +
<script>
219 +
export default {
220 +
data() {
221 +
return {
222 +
show: true,
223 +
isVisible: false
224 +
}
225 +
},
226 +
methods: {
227 +
handleVisibility(isVisible) {
228 +
this.isVisible = isVisible
229 +
}
230 +
}
231 +
}
232 +
</script>
233 + 234 +
<!-- v-b-visible-display.vue -->
235 +
```
236 + 237 +
## See also
238 + 239 +
For more details on `IntersectionObserver`, refer to the
240 +
[MDN documentation](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4