src/directives/visible/README.md
v-b-visibleis a lightweight directive that allows you to react when an element becomes visible in the viewport and/or when it moves out of the viewport (or is no longer visible).
v-b-visible will call your callback method with a boolean value indicating if the element is
visible (intersecting with the viewport) or not.display: none), as long as the element is
within (or partially within) the viewport, or within the optional offset. Note: transitioning to a
non-visible state due to v-if="false" cannot be detected.<b-img-lazy>.v-b-visible directive requires browser support of
IntersectionObserver.
For older browsers that do not support IntersectionObserver, you will need to use a
polyfill.IntersectionObserver support is not detected, then v-b-visible will assume the element is
always visible, and will call the callback once with the argument set to true.<div v-b-visible.[mod1].[mod2]="callback">content</div>
Where callback is required:
true indicates that the element is intersecting (partially or entirely
visible) in the viewport, or false if the element is not visible/intersecting with the viewport.
The callback will be called each time the element's visibility changes (except when the once
modifier is used. See below for details)Where [mod1] or [mod2] can be (all optional):
0.once. When this modifier is present, the callback will be called only once the first
time the element is visible (with the argument of true indicating the element is
intersecting/visible). Note the callback may be called prior to this with an argument of false
signifying the element is not intersecting/visible.The order of the modifiers is not important.
In all use cases, the callback function is required.
<template>
<div v-b-visible="visibleHandler"> ... </div>
</template>
<script>
export default {
methods: {
visibleHandler(isVisible) {
if (isVisible) {
// Do something
} else {
// Do something else
}
}
}
}
</script>
In this example, the modifier value represents 350px (if the element is outside of the physical viewport by at least 350px, then it will be considered "visible"):
<template>
<div v-b-visible.350="visibleHandler"> ... </div>
</template>
<script>
export default {
methods: {
visibleHandler(isVisible) {
if (isVisible) {
// Do something
} else {
// Do something else
}
}
}
}
</script>
once modifier<template>
<div v-b-visible.once="visibleHandler"> ... </div>
</template>
<script>
export default {
methods: {
visibleHandler(isVisible) {
if (isVisible) {
// This will only ever happen once, when the
// element has become visible for the first time
} else {
// This may happen zero or more times before
// the element becomes visible, but will never
// happen after the element has become visible
}
}
}
}
</script>
once and offset modifiers<template>
<div v-b-visible.once.350="visibleHandler"> ... </div>
</template>
<script>
export default {
methods: {
visibleHandler(isVisible) {
if (isVisible) {
// This will only ever happen once, when the
// element is outside of the physical viewport
// by at least 350px for the first time
} else {
// This may happen zero or more times before
// the element becomes visible, but will never
// happen after the element has become visible
}
}
}
}
</script>
Here are two live examples showing two common use cases.
Scroll the container to see the reaction when the <b-badge> scrolls into view. Note that
visibility state will also change if the element is scrolled out of the viewport.
<template>
<div>
<div
:class="[isVisible ? 'bg-info' : 'bg-light', 'border', 'p-2', 'text-center']"
style="height: 85px; overflow-y: scroll;"
>
<p>{{ text }}</p>
<b-badge v-b-visible="handleVisibility">Element with v-b-visible directive</b-badge>
<p>{{ text }}</p>
</div>
<p class="mt-2">
Visible: {{ isVisible }}
</p>
</div>
</template>
<script>
export default {
data() {
return {
isVisible: false,
text: `
Quis magna Lorem anim amet ipsum do mollit sit cillum voluptate ex nulla
tempor. Laborum consequat non elit enim exercitation cillum aliqua
consequat id aliqua. Esse ex consectetur mollit voluptate est in duis
laboris ad sit ipsum anim Lorem. Incididunt veniam velit elit elit veniam
Lorem aliqua quis ullamco deserunt sit enim elit aliqua esse irure. Laborum
nisi sit est tempor laborum mollit labore officia laborum excepteur commodo
non commodo dolor excepteur commodo. Ipsum fugiat ex est consectetur ipsum
commodo tempor sunt in proident. Non elixir food exorcism nacho tequila tasty.
`
}
},
methods: {
handleVisibility(isVisible) {
this.isVisible = isVisible
}
}
}
</script>
<!-- v-b-visible-scroll.vue -->
One use case for this, when combined with the once modifier, is to see if a user has scrolled to
the bottom of a page or scrollable div (i.e. has "read" the entire terms of service).
Click the button to change the <div> visibility state. Note that visibility state will also change
if the element is scrolled out of the viewport.
<template>
<div>
<b-button @click="show = !show" class="mb-2">Toggle display</b-button>
<p>Visible: {{ isVisible }}</p>
<div class="border p-3" style="height: 6em;">
<!-- We use Vue's `v-show` directive to control the CSS `display` of the div -->
<div v-show="show" class="bg-info p-3">
<b-badge v-b-visible="handleVisibility">Element with v-b-visible directive</b-badge>
</div>
</div>
</div>
</template>
<script>
export default {
data() {
return {
show: true,
isVisible: false
}
},
methods: {
handleVisibility(isVisible) {
this.isVisible = isVisible
}
}
}
</script>
<!-- v-b-visible-display.vue -->
For more details on IntersectionObserver, refer to the
MDN documentation