Class IntersectionObserver

Namespace

CSharpToJavaScript.APIs.JS

Assembly

CSharpToJavaScript.dll

The IntersectionObserver interface of the Intersection Observer API provides a way to asynchronously observe changes in the intersection of a target element with an ancestor element or with a top-level document's 'viewport'. The ancestor element or viewport is referred to as the root.

[Value("IntersectionObserver")]
public class IntersectionObserver

Inheritance

object

IntersectionObserver

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

When an IntersectionObserver is created, it's configured to watch for given ratios of visibility within the root. The configuration cannot be changed once the IntersectionObserver is created, so a given observer object is only useful for watching for specific changes in degree of visibility; however, you can watch multiple target elements with the same observer.

-'MutationObserver'
-'PerformanceObserver'
-'ResizeObserver'

See also on MDN

Constructors

IntersectionObserver()

public IntersectionObserver()

IntersectionObserver(IntersectionObserverCallback, IntersectionObserverInit)

The IntersectionObserver() constructor creates and returns a new IntersectionObserver object.

public IntersectionObserver(IntersectionObserverCallback callback, IntersectionObserverInit options = null)

Parameters

callback IntersectionObserverCallback

options IntersectionObserverInit

Remarks

See also on MDN

Properties

Delay

NOTE

Experimental

The delay read-only property of the IntersectionObserver interface indicates the minimum delay between notifications from this observer.

[Value("delay")]
public long Delay { get; }

Property Value

long

A positive number in milliseconds.The value is set using the option.delay argument to the IntersectionObserver() constructor.
The value is clamped to 100 or greater if IntersectionObservertrackVisibility is true, but otherwise defaults to 0.

Remarks

The delay is used to limit the rate at which notifications should be provided when tracking visibility, as this is a computationally intensive operation.
The recommendation when tracking visibility is that you set the delay to the largest tolerable value.

-Timing element visibility with the Intersection Observer API

See also on MDN

Root

The root read-only property of the IntersectionObserver interface identifies the Element or Document whose bounds are treated as the {{Glossary("bounding box")}} of the {{Glossary("viewport")}} for the element which is the observer's target.

[Value("root")]
public Union108? Root { get; }

Property Value

Union108?

A Element or Document object whose bounding box is used as the bounds of the viewport for the purposes of determining how much of the target element is visible.
The intersection of this bounding rectangle, offset by any margins specified in the options passed to the IntersectionObserver(IntersectionObserverCallback, IntersectionObserverInit) constructor, the target element's bounds, minus the bounds of every element or other object which overlaps the target element, is considered to be the visible area of the target element.If root is null, then the owning document is used as the root, and the bounds its viewport (that is, the visible area of the document) are used as the root bounds.

Remarks

If the root is null, then the bounds of the actual document viewport are used.

-Timing element visibility with the Intersection Observer API

See also on MDN

RootMargin

The rootMargin read-only property of the IntersectionObserver interface is a string with syntax similar to that of the CSS {{cssxref("margin")}} property.

[Value("rootMargin")]
public string RootMargin { get; }

Property Value

string

A string, formatted similarly to the CSS margin property's value, which contains offsets for one or more sides of the root's bounding box.
These offsets are added to the corresponding values in the root's bounding box before the intersection between the resulting rectangle and the target element's bounds.The string returned by this property may not match the one specified when the IntersectionObserver was instantiated.
For example, the result always contains four components, though the input may have fewer.If rootMargin isn't specified when the object was instantiated, it defaults to the string "0px 0px 0px 0px", meaning that the intersection will be computed between the root element's unmodified bounds rectangle and the target's bounds.
How intersections are calculated describes how the rootMargin is used in more detail.

Remarks

Each side of the rectangle represented by rootMargin is added to the corresponding side in the Root element's {{Glossary("bounding box")}} before the intersection test is performed.
This lets you, for example, adjust the bounds outward so that the target element is considered 100% visible even if a certain number of pixels worth of width or height is clipped away, or treat the target as partially hidden if an edge is too close to the edge of the root's bounding box.

See how intersections are calculated for a more in-depth look at the root margin and how it works with the root's bounding box.

See also on MDN

ScrollMargin

The scrollMargin read-only property of the IntersectionObserver interface adds a margin to all nested {{glossary("scroll container","scroll containers")}} within the root element, including the root element if it is a scroll container.

[Value("scrollMargin")]
public string ScrollMargin { get; }

Property Value

string

A string, formatted similarly to the CSS margin property's value.The specified margin defines offsets for one or more sides of a scroll container clipping rectangle.
If scrollMargin isn't specified when the object was instantiated, it defaults to the string "0px 0px 0px 0px".

Remarks

This grows or shrinks the clipping rectangle of the scrollable containers before calculating intersections.
This lets you, for example, adjust the bounds of the scroll container so that the target element is considered visible even if its pixels are not yet displayed in the container's viewport, or to treat the target as partially hidden if an edge is too close to the edge of the container's bounding box.

Note that if the root element is also a scrollable container, then the scrollMargin and IntersectionObserverrootMargin are combined to determine the effective bounding rectangle used for calculating intersections with the target.

For more information see The intersection root and scroll margin in the API overview.

See also on MDN

Thresholds

The thresholds read-only property of the IntersectionObserver interface returns the list of intersection thresholds that was specified when the observer was instantiated with IntersectionObserver(IntersectionObserverCallback, IntersectionObserverInit).

[Value("thresholds")]
public Number[] Thresholds { get; }

Property Value

Number[]

An array of intersection thresholds, originally specified using the threshold property when instantiating the observer.
If only one observer was specified, without being in an array, this value is a one-entry array containing that threshold.
Regardless of the order your original threshold array was in, this one is always sorted in numerically increasing order.If no threshold option was included when IntersectionObserver() was used to instantiate the observer, the value of thresholds is [0].

NOTE

Although the options object you can specify in the IntersectionObserverIntersectionObserver constructor has a field named threshold, this property is called thresholds.
If you accidentally use thresholds as the name of the field in your options, the thresholds array will wind up being [0.0], which is likely not what you expect.

Remarks

If only one threshold ratio was provided when instantiating the object, this will be an array containing that single value.

See the Intersection Observer page to learn how thresholds work.

See also on MDN

TrackVisibility

NOTE

Experimental

The trackVisibility read-only property of the IntersectionObserver interface indicates whether the observer is tracking target visibility in addition to element intersections.

[Value("trackVisibility")]
public bool TrackVisibility { get; }

Property Value

bool

true if visibility is being tracked for intersection calculations, and false otherwise.The value is set using the option.trackVisibility argument to the IntersectionObserver() constructor.

Remarks

-Timing element visibility with the Intersection Observer API

See also on MDN

Methods

Disconnect()

The disconnect() method of the IntersectionObserver interface stops the observer watching all of its target elements for visibility changes.

[Value("disconnect")]
public GlobalObject.Undefined Disconnect()

Returns

GlobalObject.Undefined

None (GlobalObject.Undefined).

Remarks

-Observe(Element)
-Unobserve(Element)

See also on MDN

Observe(Element)

The observe() method of the IntersectionObserver interface adds an element to the set of target elements being watched by the IntersectionObserver.
One observer has one set of thresholds and one root, but can watch multiple target elements for visibility changes in keeping with those.

[Value("observe")]
public GlobalObject.Undefined Observe(Element target)

Parameters

target Element

Returns

GlobalObject.Undefined

None (GlobalObject.Undefined).

Remarks

To stop observing the element, call Unobserve(Element).

When the visibility of the specified element crosses over one of the observer's visibility thresholds (as listed in Thresholds), the observer's callback is executed with an array of IntersectionObserverEntry objects representing the intersection changes
which occurred.
Note that this design allows multiple elements' intersection changes to be processed by a single call to the callback.

NOTE

The observer callback will always fire the first render cycle after observe() is called, even if the observed element has not yet moved with respect to the viewport.
This means that, for example, an element that is outside the viewport when observe() is called on it will result in the callback being immediately called with at least one entry with intersecting set to false.
An element inside the viewport will result in the callback being immediately called with at least one entry with intersecting set to true.

-Unobserve(Element)

See also on MDN

TakeRecords()

The takeRecords() method of the IntersectionObserver interface returns an array of IntersectionObserverEntry objects, one for each targeted element which has experienced an intersection change since the last time the intersections were checked, either explicitly through a call to this method or implicitly by an automatic call to the observer's callback.

[Value("takeRecords")]
public List<IntersectionObserverEntry> TakeRecords()

Returns

List<IntersectionObserverEntry>

An array of IntersectionObserverEntry objects, one for each target element whose intersection with the root has changed since the last time the intersections were checked.

Remarks

NOTE

If you use the callback to monitor these changes, you don&apos;t need to call this method.
Calling this method clears the pending intersection list, so the callback will not be run.

-Intersection Observer API

See also on MDN

Unobserve(Element)

The unobserve() method of the IntersectionObserver interface instructs the IntersectionObserver to stop observing the specified target element.

[Value("unobserve")]
public GlobalObject.Undefined Unobserve(Element target)

Parameters

target Element

Returns

GlobalObject.Undefined

None (GlobalObject.Undefined).

Remarks

-Intersection Observer API
-Observe(Element)

See also on MDN