What is vue-observe-visibility?
The vue-observe-visibility package is a Vue.js directive that allows you to detect when an element is visible or hidden in the viewport. This can be useful for lazy loading images, infinite scrolling, or triggering animations when elements come into view.
What are vue-observe-visibility's main functionalities?
Basic Visibility Detection
This feature allows you to detect when an element becomes visible or hidden in the viewport. The `visibilityChanged` method is called with a boolean indicating the visibility state and the IntersectionObserverEntry object.
<template>
<div v-observe-visibility="visibilityChanged">
Content to observe
</div>
</template>
<script>
export default {
methods: {
visibilityChanged(isVisible, entry) {
console.log('Element is visible:', isVisible);
}
}
};
</script>
Threshold Configuration
This feature allows you to configure the threshold at which the visibility change is detected. In this example, the `visibilityChanged` method is called when 50% of the element is visible.
<template>
<div v-observe-visibility="{ handler: visibilityChanged, options: { threshold: 0.5 } }">
Content to observe
</div>
</template>
<script>
export default {
methods: {
visibilityChanged(isVisible, entry) {
console.log('Element is visible:', isVisible);
}
}
};
</script>
Root Margin Configuration
This feature allows you to configure the root margin, which is the margin around the root element. In this example, the `visibilityChanged` method is called when the element is within 50px of the bottom of the viewport.
<template>
<div v-observe-visibility="{ handler: visibilityChanged, options: { rootMargin: '0px 0px -50px 0px' } }">
Content to observe
</div>
</template>
<script>
export default {
methods: {
visibilityChanged(isVisible, entry) {
console.log('Element is visible:', isVisible);
}
}
};
</script>
Other packages similar to vue-observe-visibility
vue-intersect
vue-intersect is a Vue.js directive that uses the Intersection Observer API to detect when an element enters or leaves the viewport. It offers similar functionality to vue-observe-visibility but with a slightly different API and additional customization options.
vue-scrollmonitor
vue-scrollmonitor is a Vue.js wrapper for the ScrollMonitor library, which allows you to monitor elements as they enter or leave the viewport. It provides more advanced features like event throttling and custom viewport offsets, making it a more feature-rich alternative to vue-observe-visibility.
vue-lazyload
vue-lazyload is a Vue.js plugin that provides lazy loading for images and other elements. While its primary focus is on lazy loading, it also includes visibility detection features similar to those in vue-observe-visibility, making it a good choice for projects that require both functionalities.
vue-observe-visibility
Detect when an element is becoming visible or hidden on the page. Demo
![sponsors logos](https://guillaume-chau.info/sponsors.png)
Table of contents
Installation
npm install --save vue-observe-visibility
⚠️ This plugin uses the Intersection Observer API that is not supported in every browser (currently supported in Edge, Firefox and Chrome). You need to include a polyfill to make it work on incompatible browsers.
Import
import Vue from 'vue'
import VueObserveVisibility from 'vue-observe-visibility'
Vue.use(VueObserveVisibility)
Or:
import Vue from 'vue'
import { ObserveVisibility } from 'vue-observe-visibility'
Vue.directive('observe-visibility', ObserveVisibility)
Browser
<script src="vue.js"></script>
<script src="https://unpkg.com/vue-observe-visibility/dist/vue-observe-visibility.min.js"></script>
The plugin should be auto-installed. If not, you can install it manually with the instructions below.
Install all the directives:
Vue.use(VueObserveVisibility)
Use specific directives:
Vue.directive('observe-visibility', VueObserveVisibility.ObserveVisibility)
Usage
The v-observe-visibility
directive is very easy to use. Just pass a function as the value:
<div v-observe-visibility="visibilityChanged">
This also works on components:
<MyComponent v-observe-visibility="visibilityChanged" />
The function will be called whenever the visiblity of the element changes with the argument being a boolean (true
means the element is visible on the page, false
means that it is not).
The second argument is the corresponding IntersectionObserverEntry object.
visibilityChanged (isVisible, entry) {
this.isVisible = isVisible
console.log(entry)
}
IntersectionObserver options
It's possible to pass the IntersectionObserver options
object using the intersection
attribute:
<div v-observe-visibility="{
callback: visibilityChanged,
intersection: {
root: ...,
rootMargin: ...,
threshold: 0.3,
},
}">
Once
It can be useful to listen for when the element is visible only once, for example to build introduction animations. Set the once
option to true
:
<div v-observe-visibility="{
callback: visibilityChanged,
once: true,
}">
Throttling visibility
You can use the throttle
options (in ms) specifying minimal state duration after which an event will be fired. It's useful when you are tracking visibility while scrolling and don't want events from fastly scrolled out elements.
<div v-observe-visibility="{
callback: visibilityChanged,
throttle: 300,
}">
You can also pass a leading
option to trigger the callback the first time when the visibility changes without waiting for the throttle delay.
I can either be visible
, hidden
or both
.
<div v-observe-visibility="{
callback: visibilityChanged,
throttle: 300,
throttleOptions: {
leading: 'visible',
},
}">
Passing custom arguments
You can add custom argument by using an intermediate function:
<div v-observe-visibility="(isVisible, entry) => visibilityChanged(isVisible, entry, customArgument)">
Here visibilityChanged
will be call with a third custom argument customArgument
.
Disabling the observer
Passing a falsy value to the directive will disable the observer:
<div
v-for="(item, index) of items"
:key="item.id"
v-observe-visibility="index === items.length - 1 ? visibilityChanged : false"
>
Example
<div id="app">
<button @click="show = !show">Toggle</button>
<label>
<input type="checkbox" v-model="isVisible" disabled/> Is visible?
</label>
<div ref="test" v-show="show" v-observe-visibility="visibilityChanged">Hello world!</div>
</div>
<script>
new Vue({
el: '#app',
data: {
show: true,
isVisible: true,
},
methods: {
visibilityChanged (isVisible, entry) {
this.isVisible = isVisible
console.log(entry)
},
},
})
</script>
License
MIT