@djx/observable NPM

@djx/observable

Observing the visibility of DOM elements

Installation

npm install --save @djx/observable

Usage

Make sure you import the component somewehere in your application first:

import '@djx/observable';

You can then use it like normal web components in your markup:

<!-- You need at least one root observable -->
<djx-observable-root>
  <!-- Observe all the time -->
  <djx-observable>
    <div>Watch me all the time, stalker</div>
  </djx-observable>

  <!-- Observe once -->
  <djx-observable once>
    <div>Observe me once then ignore me</div>
  </djx-observable>
</djx-observable-root>

Configuring the observable root node

In order for the observables to know where to attach to, you need at least one djx-observable-root component wrapped around your observables. Since the djx-observable-root uses the ResizeObserver and IntersectionObserver to determine the state of each observable, you can tweak the configuration for each root node a little bit.

<djx-observable-root
  use-root
  margin="0px 20px 20px"
  threshold="0.2"
>
  ...
</djx-observable-root>

The `use-root` option

This defines the djx-observable-root element as root for the IntersectionObserver. Default is false.

The `margin` option

The margin option of the IntersectionObserver. Read more about it here.

The `threshold` option

The threshold option of the IntersectionObserver. Read more about it here.

Using multiple observable root nodes

Sometimes you need observables to behave differently. You can define as many djx-observable-root nodes as you want. Just nest them accordingly. Here's an example:

<body>
  <!-- Observable with a 20% threshold -->
  <djx-observable-root name="ob-t20" threshold="0.2">
    <!-- Observable with a 10% threshold -->
    <djx-observable-root name="ob-t10" threshold="0.1">
      <!-- This obersvable will attach to the `ob-t10` root -->
      <djx-observable once root="ob-t10">
        <div>Trigger after 10% visible</div>
      </djx-observable>

      <!-- This obersvable will attach to the `ob-t10` root -->
      <djx-observable once>
        <div>Trigger after 10% visible</div>
      </djx-observable>

       <!-- This obersvable will attach to the `ob-t20` root -->
      <djx-observable once root="ob-t20">
        <div>Trigger after 20% visible</div>
      </djx-observable>
    </djx-observable-root>
  </djx-observable-root>
</body>

If you don't define a root-id it'll take the first parent root node

The observable state

To get notified about any dimension and position changes you can add a listener to the observable. This will be called whenever the ResizeObserver detects a change or the user resizes the browser:

<!-- Using the lit-element syntax -->
<djx-observable
  id="custom-observable"
  @update="({ detail }) => console.log(detail.offset, detail.bounds)"
></djx-observable>

<!-- Listening to the element directly -->
<script>
  const element = document.getElementById('custom-observable');

  element.addEventListener('update', ({ detail }) => {
    console.log(detail.offset, detail.bounds);
  });
</script>

Note: The lit-element syntax can only be used inside lit-elements

The visibility state

How does the state of visibility manifests itself? You have two ways of dealing with this. Go with the event or use the className.

The event based approach

You can either add a listener directly to the element or use the lit-element syntax:

<!-- Using the lit-element syntax -->
<djx-observable
  id="custom-observable"
  @visiblity-changed="({ detail }) => console.log(detail.visible)"
></djx-observable>

<!-- Listening to the element directly -->
<script>
  const element = document.getElementById('custom-observable');

  element.addEventListener('visiblity-changed', ({ detail }) => {
    console.log(detail.visible);
  });
</script>

Note: The lit-element syntax can only be used inside lit-elements

The CSS class based approach

Sometimes you just want to add a simple fade-in effect to the observable. Of course the event based approach would be too complex for this particular use-case. The observable also adds a class when the visibility changes. You can use it to make simple changes to the element via CSS:

<style>
  #custom-observable {
    transition: opacity .8s;
  }

  #custom-observable:not(.djx--is-visible) {
    opacity: 0;
  }
</style>

<djx-observable id="custom-observable">
  <div>Simple fade-in</div>
</djx-observable>