Class: VisibilityObserver

VisibilityObserver

new VisibilityObserver(granularityopt, nullable, targetFpsopt, nullable, forcePollingObserveropt, nullable)

Creates a new VisibilityObserver and starts the observation of elements.

Parameters:
Name Type Attributes Default Description
granularity Number <optional>
<nullable>
 10

the number of intersection thresholds to use for each element (see IntersectionObserver threshold documentation) -> 2: just the outer bounds - 10: 10% steps - 100: one intersection every visible percent; make sure this number fits you needs and maybe think about using multiple observers with different granularities to cover different use cases
targetFps Number <optional>
<nullable>
 VISIBILITY_BASE_FPS

target frames per second to target with polls (be aware, that higher values put more stress on the CPU)
forcePollingObserver Boolean <optional>
<nullable>
 false

set this to true, if you want to skip usage of IntersectionObserver and, instead, just use polling all the time (this is a brute-force method putting stress on the CPU, only do this for a good reason)
Source:
See:

Methods

connect(granularityopt, nullable, targetFpsopt, nullable, forcePollingObserveropt, nullable) → {VisibilityObserver}

Starts the observation of observed elements, which produces all visibility-related events.

Be sure, that the observer is started before using any detail functions (these should be safe-guarded and warn about the fact, that the observer is not connected).

Parameters:
Name Type Attributes Default Description
granularity Number <optional>
<nullable>
 10

the number of intersection thresholds to use for each element (see IntersectionObserver threshold documentation) -> 2: just the outer bounds - 10: 10% steps - 100: one intersection every visible percent; make sure this number fits you needs and maybe think about using multiple observers with different granularities to cover different use cases
targetFps Number <optional>
<nullable>
 VISIBILITY_BASE_FPS

target frames per second to target with polls (be aware, that higher values put more stress on the CPU)
forcePollingObserver Boolean <optional>
<nullable>
 false

set this to true, if you want to skip usage of IntersectionObserver and, instead, just use polling all the time (this is a brute-force method putting stress on the CPU, only do this for a good reason)
Source:
See:
  • disconnect
Returns:
the observer instance
Type
VisibilityObserver
Example
visibilityObserver.connect(100, 50);

disconnect() → {VisibilityObserver}

Stops the observation of observed elements.

Be sure to use this method before removing a VisibilityObserver to prevent trailing event registrations and timers.

Source:
See:
  • connect
Returns:
the observer instance
Type
VisibilityObserver
Example
visibilityObserver.disconnect();

getState(element) → {VisibilityState|null}

Returns the current visibility state of an element.

Parameters:
Name Type Description
element HTMLElement

the element of which to retrieve the current visibility state
Source:
Returns:
the element's visibility state or null if observer is not running
Type
VisibilityState | null
Example
if( visibilityObserver.getState(teaserElement).inViewport() ){ ... }

getViewportInfo() → {Viewport.ViewportInfo|null}

Returns information about the current state of the viewport.

This includes dimensions as well as scroll state.

Source:
Returns:
the current viewport info or null if observer is not running
Type
Viewport.ViewportInfo | null
Example
visibilityObserver.getViewportInfo().scrollTop;

getViewportObservable() → {Basic.Observable|null}

Returns an Observable, which changes on every update of the viewport.

Subscribing to this value, allows you to programmatically react to every relevant viewport change.

Source:
See:
Returns:
the observable or null if observer is not running
Type
Basic.Observable | null
Example
visibilityObserver.getViewportObservable().subscribe(() => { console.log(visibilityObserver.getViewportInfo().scrollTop); });

observe(element, calculateScrolledopt, nullable, calculateDistanceopt, nullable, autoHandleTooLargeElementsopt, nullable) → {VisibilityObserver}

Adds an element to the set of observed elements.

Parameters:
Name Type Attributes Default Description
element HTMLElement

the element to observe
calculateScrolled Boolean <optional>
<nullable>
 false

defines if the element should be observed in terms of scrolled distance inside the viewport (which is not possible by watching intersections alone), setting this to true adds the property "scrolledPercent" to the visibility state
calculateDistance Boolean <optional>
<nullable>
 false

defines if the element should be observed in terms of distance from the viewport (which is not possible by watching intersections alone), setting this to true adds the properties "distancePixels" and "distanceViewports" to the visibility state
autoHandleTooLargeElements Boolean <optional>
<nullable>
 true

defines if elements, that are larger than the viewport should automatically be handled differently, to keep property updates consistent, if no element bounds are in the viewport (this is CPU-intensive, but normally something you'll expect, set this to false, if you are sure, that you do not need continuous updates during scrolling)
Source:
See:
  • unobserve
Throws:

error if element is not an HTML element

Returns:
the observer instance
Type
VisibilityObserver
Example
visibilityObserver.observe(teaserElement);
visibilityObserver.observe(anotherTeaserElement, true, true);

unobserve(element) → {VisibilityObserver}

Removes an element from the set of observed elements.

Parameters:
Name Type Description
element HTMLElement

the element to unobserve
Source:
See:
  • observe
Returns:
the observer instance
Type
VisibilityObserver
Example
visibilityObserver.unobserve(teaserElement);