Svelte Inview

A Svelte action that monitors an element enters or leaves the viewport/parent element. Performant and efficient thanks to using Intersection Observer under the hood. Can be used in multiple projects including lazy loading images, infinite scrolling, playing/pausing the video when in the viewport, tracking user behaviour firing link pre-fetching and animations and many many more.

🔥 Check it out live here

Support if you like it ☕ 🔥

Why bother?

• 👓️ Watch for any element that enters or leaves the viewport (or another wrapper/parent element).
• 🏎️ Thanks to using Intersection Observer, Svelte Inview is blazing fast and doesn't block the main thread.
• 📦️ Tiny, yet powerful (just ~2kb). No external dependencies (well, apart from Svelte).
• 🎛️ Use it in several different scenarios such as lazy loading images, infinite scrolling, playing/pausing the video when in the viewport, firing link pre-fetching, animations and many many more.
• 🐥 Easy to use API.
• ↕️ Detects the scrolling direction.

Installation

The only thing you need is Svelte itself.

Svelte Inview is distributed via npm.

$ yarn add svelte-inview
# or
$ npm install --save svelte-inview

⚠️ Modern browsers have the full support of Intersection Observer, but if you need to support ones like IE you can use this simple polyfill. Just install it and import it in your project.

Usage

Basic Use Case

This is the most basic use case for svelte-inview. Just add the action to the element you want to track - use:inview. You can also pass other configuration props. You can see if the element is visible by checking the inView or from the inside of the callback method - on:inview_change.

<script lang="ts">
  import { inview } from 'svelte-inview';

  let isInView: boolean;
  const options = {};
</script>

  <div
    use:inview={options}
    on:inview_change={(event) => {
      const { inView, entry, scrollDirection, observer, node} = event.detail;
      isInView = inView;
    }}
    on:inview_enter={(event) => {
      const { inView, entry, scrollDirection, observer, node} = event.detail;
      isInView = inView;
    }}
    on:inview_leave={(event) => {
      const { inView, entry, scrollDirection, observer, node} = event.detail;
      isInView = inView;
    }}
    on:inview_init={(event) => {
      const { observer, node } = event.detail;
    }}>{isInView ? 'Hey I am in the viewport' : 'Bye, Bye'}</div>

Lazy Loading Images

Svelte Inview lets you easily lazy load images. For a better UX we can pass a rootMargin="50px" props, so the image will be loaded when scroll is 50px before the viewport. After it appears in the viewport, you don't want to observe it anymore, hence the unobserveOnEnter props set to true.

<script lang="ts">
  import { inview } from 'svelte-inview';
  import type { ObserverEventDetails, Options } from 'svelte-inview';

  let isInView;
  const options: Options = {
    rootMargin: '50px',
    unobserveOnEnter: true,
  };

  const handleChange = ({ detail }: CustomEvent<ObserverEventDetails>) =>
    (isInView = detail.inView);
</script>

<div use:inview="{options}" on:inview_change="{handleChange}">
  {#if isInView}
  <img src="path/to/image.jpg" />
  {:else}
  <div class="placeholder" />
  {/if}
</div>

Video Control

You can play/pause a video when it's in/out of the viewport. Simply pass correct methods in on:inview_enter and on:inview_leave callbacks.

<script lang="ts">
  import { inview } from 'svelte-inview';
  import type { ObserverEventDetails } from 'svelte-inview';

  let isInView: boolean;
  let videoRef: HTMLElement;
</script>

  <div
    use:inview
    on:inview_enter={() => videoRef.play()}
    on:inview_leave={() => videoRef.pause()}
  >
    <video width="500" controls bind:this={videoRef}>
      <source src="path/to/video.mp4" type="video/mp4" />
    </video>
  </div>

Animations

You can also add some cool animations when an element enters the viewport. To make sure the animation won't fire too soon you can pass a negative value to rootMargin. When inView is true, add an animation class to your target. Additionally, you can detect the scroll direction to make the animations even cooler!

<script lang="ts">
  import { inview } from 'svelte-inview';
  import type { ObserverEventDetails, ScrollDirection, Options } from 'svelte-inview';

  let isInView: boolean;
  let scrollDirection: ScrollDirection;
  const options: Options = {
    rootMargin: '-50px',
    unobserveOnEnter: true,
  };

  const handleChange = ({ detail }: CustomEvent<ObserverEventDetails>) => {
    isInView = detail.inView;
    scrollDirection = detail.scrollDirection.vertical;
  };
</script>

  <div use:inview={options} on:inview_change={handleChange}>
    <div
      class:animate={isInView}
      class:animateFromBottom={scrollDirection === 'down'}
      class:animateFromTop={scrollDirection === 'up'}>
      Animate me!
    </div>
  </div>

Important information about breaking changes in previous versions

Version 4 introduces new names for events. Before they were 'change' | 'leave' | 'enter' | 'init'. In version 4 they're changed to 'inview_change' | 'inview_leave' | 'inview_enter' | 'inview_init'.

This change was needed to satisfy Typescript, as the package was messing up the default types coming from svelte typings. To ensure backward compatibility, the original events names will still work for some time, but they won't be properly recognized by Typescript. To sum up, this will still work, but TS won't be happy about it:

on:change={(event) => {
  const { inView, entry, scrollDirection, observer, node} = event.detail;
  isInView = inView;
}}

To make sure it works properly and satisfy TS you'll need to change it to this:

on:inview_change={(event) => {
  const { inView, entry, scrollDirection, observer, node} = event.detail;
  isInView = inView;
}}

Version 2 was returning observe and unobserve methods on the events. In version 3 they were removed, and the observer and node are being returned instead. So if you used those methods before like this:

event.detail.observe(node);

You'll need to change it to:

event.detail.observer.observe(node);

Version 1 was using an Inview component. In version 2 that was changed to action - API is easier to consume, plus the obsolete wrapper is not longer needed. If you still want to use the component, check the documentation for version 1.

API

Props

Observer events arguments

Lifecycle events arguments

Additional Info

Usage with rootMargin

If you want to increase or decrease the area of the root, just pass the rootMargin. On the image below you can see the blue area being the root. It means that every time, the target element will enter or leave that area (or meet the specified threshold), a callback will be fired.

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Maciek Grzybek - @grzybek_maciek - [email protected] - www.maciekgrzybek.dev