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:

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%'