https://github.com/martinlaxenaire/scroll-observer
Really simple Intersection Observer helper
https://github.com/martinlaxenaire/scroll-observer
intersection-observer intersectionobserver-api javascript vanilla-javascript
Last synced: 4 months ago
JSON representation
Really simple Intersection Observer helper
- Host: GitHub
- URL: https://github.com/martinlaxenaire/scroll-observer
- Owner: martinlaxenaire
- License: mit
- Created: 2020-09-04T13:34:12.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2021-03-22T09:33:06.000Z (almost 5 years ago)
- Last Synced: 2025-10-10T04:33:39.461Z (4 months ago)
- Topics: intersection-observer, intersectionobserver-api, javascript, vanilla-javascript
- Language: JavaScript
- Homepage:
- Size: 33.2 KB
- Stars: 52
- Watchers: 3
- Forks: 6
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
Lightweight vanilla javascript library to handle intersection observers
Initializing
```javascript
import {ScrollObserver} from './src/scroll.observer.js';
const scrollObserver = new ScrollObserver();
```
In a browser, you can use the UMD files located in the `dist` directory:
```html
```
```javascript
const scrollObserver = new ScrollObserver();
```
Parameters
Basic params
The basic parameters you can specify are the same you'd use with an intersection observer (see https://developer.mozilla.org/fr/docs/Web/API/Intersection_Observer_API):
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| root | CSS selector | "viewport" | Root intersection observer parameter |
| rootMargin | String | "0px" | Root margins to use |
| threshold | array | 0 | Array of thresholds that will trigger the callback function |
```javascript
const scrollObserver = new ScrollObserver({
// root
root: document.getElementById("content"),
// rootMargins
rootMargin: "20px 0",
// threshold array
threshold: [0, 0.25, 0.5, 0.75, 1]
});
```
Observe elements
Once you've created an observer, you need to observe elements.
You can add one or multiple elements to observe thanks to the `observe()` method:
```javascript
scrollObserver.observe({
// elements to observe
elements: document.querySelectorAll(".scroll-observed-el")
});
```
You can use a CSS selector instead of a list of elements:
```javascript
// exactly the same as above
scrollObserver.observe({
// elements to observe specified with a selector
selector: ".scroll-observed-el"
});
```
There are 3 callbacks that you can use when observing an element, `onBeforeElVisible()`, `onElVisible()` and `onElHidden`, trigger by the intersection observer based on the `root`, `rootMargin` and `threshold` parameters:
```javascript
scrollObserver.observe({
// elements to observe
elements: document.querySelectorAll(".scroll-observed-el"),
// wait for 200ms (cumulative) each time one of this element is visible
stagger: 200,
// an ".scroll-observed-el" element became visible
onBeforeElVisible: (observedEl) => {
// observedEl is an object containing the original HTML element, its bounding rectangle and other properties
console.log(observedEl);
},
// an ".scroll-observed-el" element became visible and its staggering timeout has run
onElVisible: (observedEl) => {
// observedEl is an object containing the original HTML element, its bounding rectangle and other properties
console.log(observedEl);
},
// an ".scroll-observed-el" element became hidden
onElHidden: (observedEl) => {
// observedEl is an object containing the original HTML element, its bounding rectangle and other properties
console.log(observedEl);
},
});
```
Complete parameter list
Here is a complete list of all `observe()` method parameters:
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| elements | array of HTML elements | [] | elements to observe |
| selector | string | null | elements to observe based on a CSS selector |
| keepObserving | bool | false | Whether we should keep observing the element after it has been in and out of view |
| triggerRatio | float between 0 and 1 | 0 | The ratio at which the visible/hidden callback should be called |
| alwaysTrigger | bool | true | Whether it should trigger the visible callback multiple times or just once |
| stagger | float | 0 | Number of milliseconds to wait before calling the visible callback (used for staggering animations) |
| onBeforeElVisible | function(observedEl) | void | Function to execute right when this element become visible. Use it to change this element staggering property for example |
| onElVisible | function(observedEl) | void | Function to execute when this element become visible, after the staggering timeout |
| onElHidden | function(observedEl) | void | Function to execute when this element become hidden |
Unobserve elements
You can decide to stop observing elements whenever you want.
Unobserving one element
You can pass a HTML element to the `unobserveEl()` method:
```javascript
scrollObserver.unobserveEl(document.getElementById("observed-el"));
```
Unobserving multiple elements
You can pass an array of elements to the `unobserveEls()` method:
```javascript
scrollObserver.unobserveEls(document.querySelectorAll(".scroll-observed-el"));
```
Unobserving all elements and disconnect observer
You can also decide to unobserve all elements and disconnect your observer:
```javascript
scrollObserver.unobserveAll();
```
Events
There are 4 events you can use, `onError()`, `onBeforeElVisible()`, `onElVisible()` and `onElHidden()`:
```javascript
scrollObserver.onError(() => {
// intersection observer API is not supported, do something
}).onBeforeElVisible((observedEl) => {
// called each time an observed element become visible
console.log(observedEl);
}).onElVisible((observedEl) => {
// called each time an observed element become visible but after its staggering timeout
console.log(observedEl);
}).onElHidden((observedEl) => {
// called each time an observed element become hidden
console.log(observedEl);
});
```