@svelte-plugins/viewable

@svelte-plugins/viewable

A simple rule-based approach to tracking element viewability.

This provides the ability to define multiple viewability rules with callbacks for a single element. This comes in handy for instrumentation (specifically dwell time), ad tracking and beaconing, lazy-loading content or images, or doing fancy things at various trigger points.

If you're simply looking for a Svelte flavor of IntersectionObserver visit svelte-intersection-observer.

Try it in the Svelte REPL.

Install

yarn add -D @svelte-plugins/viewable

# or with NPM

npm i -D @svelte-plugins/viewable

Usage

<script>
  import Viewable from "@svelte-plugins/viewable";

  const immediately = (definition) => {
    console.log('element has crossed the viewport');
  };

  const dwell = ({ percentage, duration }) => {
    console.log(`${percentage}% of the element was visible for at least ${duration} consecutive seconds.`);
  };

  const rules = {
    // do something when the element enters the viewport
    immediately: { duration: 0, percentage: 0, fn: immediately },
    // do something when 50% of the element is visible for 4 seconds (consecutively)
    dwell: { duration: 4.5, percentage: 50, fn: dwell },
  };

  let element;
</script>

<Viewable {rules} {element}>
  <div bind:this={element}>Hello World</div>
</Viewable>

Try the basic example in Svelte REPL.

API

Props

Prop name	Description	Value
element	Element to observe	HTMLElement
rules	Viewability rules	object (default: null)
intervalRate	Rate to check measurement while intersecting (ms)	number (default: 200)
gridSize	Size of the obstruction grid	number (default: 20)
detectObstructions	If true, obstructions impacting the element will affect measurement	'boolean' (default: false)
root	Containing element	null or HTMLElement (default: null)
rootMargin	Margin offset of the containing element	string (default: "0px")
intersecting	true if the observed element is intersecting	boolean (default: false)
observer	IntersectionObserver instance	IntersectionObserver
entry	Observed element metadata	IntersectionObserverEntry
debug	If true, debug ouput will be logged to console	boolean (default: false)

rules

Prop name	Description	Value
duration	Consecutive time (seconds) that the element must be in view	number (default: 0)
percentage	Percentage of the element that must be viewable	number (default: 0)
repeat	If true, the rule will be applied indefinitely v once	function (default: null)
fn	Callback function to execute when rule has been met	function (default: null)

const rules = {
  dwell: {
    duration: 1,
    percentage: 50,
    fn: () => {
      console.log('50% of the element was visible for at least 1 consecutive second.');
    }
  }
}

Debug props

The properties below can be used to assist with debugging any issues you might have (ex: bind:duration, bind:percent, etc.)

Prop name	Description	Value
duration	Viewable duration of the tracked element	number (default: 0)
percent	Percentage of total viewable area (X+Y)	number (default: 0)
percentX	Percentage of horizontal viewable area	number (default: 0)
percentY	Percentage of vertical viewable area	number (default: 0)

Events

• on:observe: Fired when an intersection change occurs (type IntersectionObserverEntry)
• on:intersect: Fired when an intersection change occurs and the element is intersecting (type IntersectionObserverEntry)
• on:complete: Fired when all rules have been executed

Changelog

Changelog

License

MIT