Nostalgic Pizza Manager

    @svelte-plugins/viewable

    1.0.1 • Public • Published

    Unit Tests Integration Tests codecov

    @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

    Install

    npm i @svelte-plugins/viewable

    DownloadsWeekly Downloads

    22

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    33.8 kB

    Total Files

    11

    Last publish

    Collaborators

    • dysfunc