vue-on-visible

Vue-On-Visible

Easily observe changes in an elements visibility & viewport location.

Designed to help you improve performance and integrate interactivity in response to an elements position on the page.

Example use cases:

1. Trigger an animation on elements entering and exiting the viewport.
2. Lazy loading an image when an element is 10% below the viewport.

See Demo.

This uses the Interaction Observer API and includes a polyfill enabling support in the following browsers:

6+

7+

4.4+

---

Table of contents

• Installation
• Component
• Directive
• Properties
• Offsets

Installation

npm install --save vue-on-visible

Importing

Install Directive and Components

import Vue from 'vue'
import OnVisible from 'vue-on-visible'

Vue.use(OnVisible)

Directive

Use the v-on-visible directive to integrate visibility updates into your own components.

PropName	Type	Default	Description
onUpdate	Function	n/a - REQUIRED	Function to be called when visibility changes occur.
repeat	BOOLEAN	false	Trigger updates on every enter & exit of viewport?
topOffset	STRING	"0%"	When to trigger visibility updates. See Offsets for an explanation.
bottomOffset	STRING	"0%"	When to trigger visibility updates. See Offsets for an explanation.

Template:

  <YourComponent v-on-visible="{onUpdate, topOffset, bottomOffset, repeat}" />

Component:

const YourComponent = {
  data() {
    return {
      topOffset: '0%',
      bottomOffset: '0%',
      repeat: true 
    }
  },
  methods: {
    onUpdate(item) {
      // Do something with values...
      // isVisible, isAbove, isBelow, isPartiallyAbove, isPartiallyBelow, intersectionRatio
      // See Properties Section for details
    }
  }
}
  

Component

Using built-in component <OnVisible> with slot-scope for updates on visibility changes.

In this example, Intersection Point is 10% from the top and bottom inside the viewport.

<OnVisible topOffset="-10%" bottomOffset="-10%" :repeat="true">
  <div slot-scope="onVisible">
    <!-- SEE PROPERTIES SECTION BELOW FOR AVAILABLE PROPS -->
    <YourComponent isVisible="onVisible.isVisible" isBelow="onVisible.isBelow"/>
  </div>
</OnVisible>

Properties

The following properties will be send on all visibility updates:

PropName	Type	Description
isVisible	BOOLEAN	Component is in viewport
isAbove	BOOLEAN	Component is above viewport
isBelow	BOOLEAN	Component is below viewport
isPartiallyAbove	BOOLEAN	Component is in viewport, but also above viewport
isPartiallyBelow	BOOLEAN	Component is in viewport, but also below viewport
intersectionRatio	NUMBER	Amount of component visible. Decimal between 0 - 1

Offsets

The default offset will trigger visibility changes when your component enters/exits the viewport at the top or bottom. You can change this behavior by providing your own offsets object. Negative offsets are triggered inside of the viewport, while positive offsets are triggered outside the viewport.

For visibility changes to trigger when an element is outside the viewport use a positive number.

// Visibility changes occur 10% above the top of the viewport, and 10% below the bottom of the viewport.
const topOffset = '10%'
const bottomOffset = '10%'

For visibility changes to trigger when an element is inside the viewport use a negative number.

// Visibility changes occur 10% below the top of the viewport, and 10% above the bottom of the viewport.
const topOffset = '-10%'
const bottomOffset = '-10%'