https://github.com/rdmurphy/scroll-scene-element
📜 A tiny custom element for all your scrollytelling needs!
https://github.com/rdmurphy/scroll-scene-element
custom-elements javascript scrollytelling web-components
Last synced: 11 months ago
JSON representation
📜 A tiny custom element for all your scrollytelling needs!
- Host: GitHub
- URL: https://github.com/rdmurphy/scroll-scene-element
- Owner: rdmurphy
- License: mit
- Created: 2022-03-18T16:59:03.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2022-04-29T03:18:53.000Z (about 4 years ago)
- Last Synced: 2025-06-05T06:25:59.758Z (about 1 year ago)
- Topics: custom-elements, javascript, scrollytelling, web-components
- Language: TypeScript
- Homepage: https://rdmurphy.github.io/scroll-scene-element/sticky
- Size: 305 KB
- Stars: 27
- Watchers: 4
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `` element
A tiny custom element for all your scrollytelling needs! The successor to [`@newswire/scroller`](https://github.com/rdmurphy/scroller).
## Key features
- 🐜 **~700 bytes** brotli'ed, **~800 bytes** gzip'ed
- 👀 Uses a highly-performant **[Intersection Observer](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)** to monitor scrolling changes
- 📚 Smartly uses scroll events to **calculate scroll progress** only when needed
- 🌻 Each `` element may **have its own** `offset` and **opt-in** to `progress` events
- 🙅🏽 **No dependencies**
## Examples
- [Basic usage](https://rdmurphy.github.io/scroll-scene-element/basic)
- [Sticky graphics](https://rdmurphy.github.io/scroll-scene-element/sticky)
- [Progress events](https://rdmurphy.github.io/scroll-scene-element/progress)
## Installation
```sh
npm install scroll-scene-element
// or
yarn add scroll-scene-element
// or
pnpm add scroll-scene-element
```
## Usage
In your HTML add `` container elements around every "scene" you want to track the progression of in your interactive. Feel free to use these elements as the containers of your graphics or other dynamic content and style them as needed - all progression and scroll depth changes will be tracked on the tag and its contents.
```html
Scene 1
This is the first scene.
Scene 2
This is the first scene.
Scene 3
This is the first scene.
```
Then import the script as an ES module in your bundle or load via a script tag to upgrade the `` elements:
```js
import 'scroll-scene-element';
```
_or_
```html
```
If you have experience with [Scrollama](https://github.com/russellgoldenberg/scrollama) or [`@newswire/scroller`](https://github.com/rdmurphy/scroller) it may be surprising that there's no "init" step. Thanks to custom elements the initalization happens automatically just by using ``.
Events with `` work just like others in JavaScript giving you the same amount of flexibility. (And familiarity!) `scroll-scene-enter`, `scroll-scene-exit` and `scroll-scene-progress` all bubble up to `document`. If you know there will only be a single set of `` elements on a page you may listen on `document` directly:
```js
document.addEventListener('scroll-scene-enter', (event) => {
// "event" is a CustomEvent, giving it has a `detail` property
const detail = event.detail;
// the triggering element
const element = event.element;
// just like in standard DOM events, "target" is also the triggering element
const target = event.target;
// the bounds of the triggering element
const bounds = detail.bounds;
// whether the page was scrolling up or down when the event was triggered
const isScrollingDown = detail.isScrollingDown;
// the offset used for this element
const offset = detail.offset;
});
```
But what if you have more than one set of `` elements on a page? You might instead attach your listener to a parent element of each set of `` elements:
```js
const container = document.querySelector('.scrollytelling-container');
container.addEventListener('scroll-scene-enter', (event) => {
// no need to allow it to bubble up to `document`
event.stopPropagation();
// "event" is a CustomEvent, giving it has a `detail` property
const detail = event.detail;
// ...
});
```
And finally - you may attach your listener to each `` element individually:
```js
const scenes = document.querySelectorAll('scroll-scene');
scenes.forEach((scene) => {
scene.addEventListener('scroll-scene-enter', (event) => {
// no need to allow it to bubble up to `document`
event.stopPropagation();
// "event" is a CustomEvent, giving it has a `detail` property
const detail = event.detail;
// ...
});
});
```
Maybe you only need to know the first time a scene enters (or exits) the viewport? You can use the native `once` option with `addEventListener`:
```js
const scene = document.querySelector('scroll-scene');
scene.addEventListener(
'scroll-scene-enter',
() => {
console.log('Entered!');
},
{ once: true },
);
scene.addEventListener(
'scroll-scene-exit',
() => {
console.log('Exited!');
},
{ once: true },
);
```
If a `` element opts-in to `progress` tracking, it will emit a `scroll-scene-progress` event when the progress changes once it enters and stop emitting the event once it exits. This event will bubble up to `document`:
```html
Scene 1
This is the first scene.
```
```js
const scene = document.querySelector('scroll-scene');
scene.addEventListener('scroll-scene-progress', (event) => {
// "event" is a CustomEvent, giving it has a `detail` property
const detail = event.detail;
// the triggering element
const element = event.element;
// `event.target` is also the triggering element, just like in standard DOM events
const target = event.target;
// the bounds of the triggering element
const bounds = detail.bounds;
// the offset used for this element
const offset = detail.offset;
// the progress of the element from 0 to 1
const progress = detail.progress;
});
```
## Attributes
A `` element has two optional attributes:
- `offset`: a number between 0 and 1 that determines how far from the top of the viewport the element must be before a `scroll-scene-enter` or `scroll-scene-exit` event is triggered. Defaults to `0.5`.
- `progress`: a boolean that determines whether the `scroll-scene-progress` event is triggered. Defaults to `false`.
These can be set on the `` element as an attribute or be passed in as a property.
```html
```
```js
const scene = document.querySelector('scroll-scene');
// as properties
scene.offset = 0.75;
scene.progress = true;
// as attributes
scene.setAttribute('offset', '0.75');
scene.setAttribute('progress', '');
```
## Events
### Viewport events
**`scroll-scene-enter`** is emit when an element enters the viewport. **`scroll-scene-exit`** is emit when an element exits the viewport. Both events bubble up to `document`. They both have a `detail` property that contains the following:
- `bounds`: the bounds ([`DOMRectReadOnly`](https://developer.mozilla.org/en-US/docs/Web/API/DOMRectReadOnly)) of the triggering element as made available within the `IntersectionObserver` callback
- `element`: the triggering element
- `isScrollingDown`: whether the page was scrolling up or down when the event was triggered
- `offset`: the offset used for this element
### Progress event
**`scroll-scene-progress`** is emitted when the progress of an element changes. It bubbles up to `document` and has a `detail` property that contains the following:
- `bounds`: the bounds ([`DOMRect`](https://developer.mozilla.org/en-US/docs/Web/API/DOMRect)) of the triggering element
- `element`: the triggering element
- `offset`: the offset used for this element
- `progress`: the progress of the element from 0 to 1
## License
MIT