Consider associating threshold with a target rather than the instance

[philipwalton]

As the spec stands today, having the threshold value as a property of the instance make the API quite a bit more complex than it needs to be in any situation that involves observing multiple elements at multiple thresholds via a single IntersectionObserver instance.

Consider an example that wants to observe these three element/threshold combination:

• #foo at threshold 0.
• #bar at threshold 0.5
• #quz at threshold 1

To observe all of these elements using a single IntersectionObserver instance today, you have to instantiate the IntersectionObserver with a threshold of [0, 0.5, 1], and then in the callback you have to loop through each of the targets to make sure it has passed the appropriate threshold (e.g. #qux will trigger the callback when passing a threshold of 0 and 0.5 even though you only care about 1).

A second problem with the current API is, in the above example if I decide I no longer want to monitor #foo for intersections, I can unobserve() the #foo element, but I can't stop observing the 0 threshold, so now #bar and #qux will trigger at a threshold of 0 even though neither element cares about that threshold.

At minimum, we should add a method to update the threshold value, but I think associating the threshold(s) with the targets is a much more intuitive approach.

Here's how I'd want to write the above example:

const io = new IntersectionObserver((records) => {
  // ...
});
io.observe(document.querySelector('#foo'), {threshold: [0]});
io.observe(document.querySelector('#bar'), {threshold: [0.5]});
io.observe(document.querySelector('#qux'), {threshold: [1]});

With these change, the callback is not called for #foo on any threshold other than 0, which means I can avoid writing the logic to check the threshold level in the callback.

It also means I can later call io.unobserve(document.querySelector('#foo')) and not have to worry about the 0 threshold lingering around unnecessarily.

If an element needs to be observed at multiple thresholds but later only one of those threshold values needs to be unobserved, you could do so by specifying the threshold in the second argument to unobserve() exactly as you do in observe().

For example, to observe #foo at threshold 0 and 1 and then later only observe it at 0 you could do the following:

// Observe #foo at 0 and 1.
io.observe(document.querySelector('#foo'), {threshold: [0, 1]});

// Stop observing at 1 but continue to observe at 0.
io.unobserve(document.querySelector('#foo', {threshold: [1]});

[ojanvafai]

Do you have example use cases where you want to do these things? Could the issues you list could be fixed by having multiple IntersectionObservers?

I think adding a method to update the threshold value is easy and simple and we've heard that from multiple folks. So we may as well.

Having observe/unobserve take a threshold argument seems way more complicated both from an implementation and a web developer perspective. So, I'd want to identify what the use cases are first.

[philipwalton]

Do you have example use cases where you want to do these things?

Yeah, the primary example is my autotrack library, which has an impression tracker plugin, which takes a configuration option in the form of an array of element/threshold mappings.

The basic idea is users specify a list of element IDs and how much each element should be visible before it's considered an "impression", at which point an event is sent to Google Analytics.

I recently started working on a new feature to allow users to add/remove individual element observations, and that's when I discovered that if users want to remove an element at a threshold that no other element is observing, I either have to disconnect() and create a brand new instance or continue observing at the unused threshold.

Anyway, in this use cases there's a definite and direct association between each element and the threshold it's to be observed at.

Could the issues you list could be fixed by having multiple IntersectionObservers?

It could, though IIRC you mentioned to me once that creating an instance per target is more expensive, and it's better to just use a single instance if possible.

I think adding a method to update the threshold value is easy and simple and we've heard that from multiple folks. So we may as well.

+1

Having observe/unobserve take a threshold argument seems way more complicated both from an implementation and a web developer perspective. So, I'd want to identify what the use cases are first.

I can see how it'd be more complicated from an implementation perspective, but I think almost all use cases for developers involve thinking about thresholds as they related to elements. If it's not that big of a deal to create multiple instance, then it becomes much less of an issue.

[ojanvafai]

Creating an instance per threshold should be totally fine. Realistically, there will probably be <10 thresholds, right? Even creating an instance per observe call is not terrible. It's somewhat less efficient and scales less well to large numbers of observations.

[szager-chromium]

What would the behavior be for changing thresholds? At a minimum, changing thresholds would entail running the observation algorithm immediately to re-slot all existing observations. And then do we send notifications for all targets to show that they're in a different slot? If we don't do that, then what do we do with a target that would have generated a notification with the old set of thresholds, but wouldn't generate a notification had the the new thresholds always been in effect?

I'm afraid that allowing dynamic threshold changes will be a can of worms.

[ojanvafai]

I was picturing that it would queue up a new run of the rendering pipeline and then go through the usual algorithm with no other changes. Any records queued before the threshold change would still get delivered.

This is similar to how calling "observe" queues up another run of the rendering pipeline.

[szager-chromium]

OK, but the criterion for generating a notification is: "did my slot in the thresholds vector change since the last observation?" It's not clear to me how to answer that question when the thresholds vector has been completely replaced.

[ojanvafai]

Yeah. That is kind of tricky. I think the developer expectation would be to redo the math of what your slot would have been, but that requires implementations to track the old ratio instead of the index into the thresholds array.

So, [0, 0.5] to [0, 0.6] with an element that's 0.7 visible would not trigger a callback, but would if the element was 0.55 visible. Alternately, we could say that they all trigger callbacks whenever the threshold value is changed.