vue-waypoint

VueWaypoint

trigger functions and events based on the element position on the screen

Demo

Simple demo page

Open your browser console and see what's going on while scrolling up and down

Features

• Vue 3
• No dependencies
• Flexible
• Typescript
• Battle tested
• Customizable
• Solid project (5+ years)
• Supports slots

Getting started

npm

npm i vue-waypoint

Vue component

<template>
  <Waypoint @change="onChange">
    <!-- anything you want here -->
  </Waypoint>
</template>

<script lang="ts">
  import { defineComponent } from "vue";
  import { Waypoint } from "vue-waypoint";

  export default defineComponent({
    name: "SomeComponent",
    components: {
      Waypoint,
    },
    setup() {
      const onChange = (waypointState) => {
        // Going can be:
        // IN
        // OUT
        console.log(waypointState.going);

        // Direction can be:
        // UP
        // DOWN
        // LEFT
        // RIGHT
        console.log(waypointState.direction);
      };

      return { onChange };
    },
  });
</script>

Props

active

• Can use a reactive variable
• Can set true/false dynamically

Usage:

• Enable the waypoint: <Waypoint :active="true" />
• Disable the waypoint: <Waypoint :active="false" />

options

• Useful for inner div detection
• Trigger change event a portion of the element is completely on screen
• Is an official IntersectionObserverInit implementation

Usage:

• Set a custom IntersectionObserver options: <Waypoint :options="options" />
• Read what you can do with options: IntersectionObserverInit docs

Options example:

const options: IntersectionObserverInit = {
  root: document,
  rootMargin: "0px 0px 0px 0px",
  threshold: [0.25, 0.75],
};

tag

• Set your preferred tag for the element

• Defaults to div

• Waypoint as div: <Waypoint :tag="'div'" /> --> renders --> <div class="waypoint"></div>

• Waypoint as span: <Waypoint :tag="'span'" /> --> renders --> <span class="waypoint"></span>

• Waypoint as p: <Waypoint :tag="'p'" /> --> renders --> <p class="waypoint"></p>

disableCssHelpers

• Disable automatic CSS classes on the Waypoint component
• Defaults to false

Usage:

• Enable helpers (default): <Waypoint :disableCssHelpers="false" />
• Disable helpers: <Waypoint :disableCssHelpers="true" />

DOM result:

• With CSS helpers: <Waypoint /> --> renders --> <div class="waypoint going-in direction-down"></div>
• Without CSS helpers: <Waypoint :disableCssHelpers="true" /> --> renders --> <div></div>

CSS helpers

• Zero configuration needed
• Useful for simple CSS animations

The component comes with three classes:

• waypoint: set when the waypoint is ready
• going-in, going-out: dynamically changed when the waypoint comes in and out
• direction-up, direction-down, direction-left, direction-right: dynamically changed when the direction changes

Examples:

• <Waypoint class="waypoint going-in direction-up" /> - the element is visible and came from bottom and is going top (natural scroll)
• <Waypoint class="waypoint going-in direction-down" /> - the element is visible and came from top and is going up (reverse natural scroll)
• <Waypoint class="waypoint going-out direction-up" /> - the element is not visible and came from bottom and is going top
• <Waypoint class="waypoint going-out direction-down" /> - the element is not visible and came from top and is going up

Events

change

Emitted every time the waypoint detects a change.

<template>
  <Waypoint @change="onChange" />
</template>

function onChange(waypointState) {
  /* ... */
}

interface WaypointState {
  el: Element;
  going: "IN" | "OUT";
  direction: "UP" | "DOWN" | "LEFT" | "RIGHT";
}

Development

• Fork the repository
• Run the project (npm i && npm run dev)
• Follow Conventional Commits spec for your commits
• Open a pull request

LEGACY: Vue2 and Nuxt version

vue-waypoint for Vue2 repository

Changelog

4.3.0 (2023-08-28)

Features

• added support for SSR environments (#77) (1ae537b)