@djx/observable
v0.3.1
Published
Observes visibility of DOM elements
Downloads
13
Readme
@djx/observable
Observing the visibility of DOM elements
Installation
npm install --save @djx/observableUsage
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-idit'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-elementsyntax 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-elementsyntax 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>The default name for the visibility class is
djx--is-visible