Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/metonym/svelte-intersection-observer
Detect if an element is in the viewport using the Intersection Observer API
https://github.com/metonym/svelte-intersection-observer
conditional intersection-event intersection-observer lazy-loading svelte svelte-component typescript-definitions viewport
Last synced: 6 days ago
JSON representation
Detect if an element is in the viewport using the Intersection Observer API
- Host: GitHub
- URL: https://github.com/metonym/svelte-intersection-observer
- Owner: metonym
- License: mit
- Created: 2020-04-06T00:46:00.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-09-14T16:23:51.000Z (about 2 months ago)
- Last Synced: 2024-10-20T05:57:56.406Z (16 days ago)
- Topics: conditional, intersection-event, intersection-observer, lazy-loading, svelte, svelte-component, typescript-definitions, viewport
- Language: Svelte
- Homepage: https://metonym.github.io/svelte-intersection-observer/
- Size: 1.19 MB
- Stars: 326
- Watchers: 4
- Forks: 8
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# svelte-intersection-observer
[![NPM][npm]][npm-url]
> Detect if an element is in the viewport using the [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).
Try it in the [Svelte REPL](https://svelte.dev/repl/8cd2327a580c4f429c71f7df999bd51d).
## Installation
```sh
# NPM
npm i svelte-intersection-observer
# pnpm
pnpm i svelte-intersection-observer
# Bun
bun i svelte-intersection-observer
# Yarn
yarn add svelte-intersection-observer
```
## Usage
### Basic
Use the [`bind:this`](https://svelte.dev/docs#bind_element) directive to pass an element reference to the `IntersectionObserver` component.
Then, simply bind to the reactive `intersecting` prop to determine if the element intersects the viewport.
```svelte
import IntersectionObserver from "svelte-intersection-observer";
let element;
let intersecting;
{intersecting ? "Element is in view" : "Element is not in view"}
Hello world
```
### Once
Set `once` to `true` for the intersection event to occur only once. The `element` will be unobserved after the first intersection event occurs.
```svelte
import IntersectionObserver from "svelte-intersection-observer";
let elementOnce;
let intersectOnce;
{intersectOnce ? "Element is in view" : "Element is not in view"}
Hello world
```
### `let:intersecting`
An alternative to binding to the `intersecting` prop is to use the `let:` directive.
In the following example, the "Hello world" element will fade in when its containing element intersects the viewport.
```svelte
import IntersectionObserver from "svelte-intersection-observer";
import { fade } from "svelte/transition";
let node;
{#if intersecting}
Hello world
{/if}
```
### `on:observe` event
The `observe` event is dispatched when the element is first observed and also whenever an intersection event occurs.
```svelte no-eval
{
console.log(e.detail); // IntersectionObserverEntry
console.log(e.detail.isIntersecting); // true | false
}}
>
Hello world
```
### `on:intersect` event
As an alternative to binding the `intersecting` prop, you can listen to the `intersect` event that is dispatched if the observed element is intersecting the viewport.
**Note**: Compared to `on:observe`, `on:intersect` is dispatched only when the element is _intersecting the viewport_. In other words, `e.detail.isIntersecting` will only be `true`.
```svelte no-eval
{
console.log(e.detail); // IntersectionObserverEntry
console.log(e.detail.isIntersecting); // true
}}
>
Hello world
```
## API
### Props
| Name | Description | Type | Default value |
| :----------- | :---------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------- | :------------ |
| element | Observed element | `HTMLElement` | `null` |
| once | Unobserve the element after the first intersection event | `boolean` | `false` |
| intersecting | `true` if the observed element is intersecting the viewport | `boolean` | `false` |
| root | Containing element | `null` or `HTMLElement` | `null` |
| rootMargin | Margin offset of the containing element | `string` | `"0px"` |
| threshold | Percentage of element visibile to trigger an event | `number` between 0 and 1, or an array of `number`s between 0 and 1 | `0` |
| entry | Observed element metadata | [`IntersectionObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry) | `null` |
| observer | `IntersectionObserver` instance | [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver) | `null` |
### Dispatched events
- **on:observe**: fired when the element is first observed or whenever an intersection change occurs
- **on:intersect**: fired when the element is intersecting the viewport
The `e.detail` dispatched by the `observe` and `intersect` events is an [`IntersectionObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry) interface.
Note that all properties in `IntersectionObserverEntry` are read-only.
IntersectionObserverEntry
```ts
interface IntersectionObserverEntry {
target: HTMLElement;
time: number;
isIntersecting: boolean;
isVisible: boolean;
intersectionRatio: number;
intersectionRect: {
bottom: number;
height: number;
left: number;
right: number;
top: number;
width: number;
x: number;
y: number;
};
rootBounds: {
bottom: number;
height: number;
left: number;
right: number;
top: number;
width: number;
x: number;
y: number;
};
boundingClientRect: {
bottom: number;
height: number;
left: number;
right: number;
top: number;
width: number;
x: number;
y: number;
};
}
```
## Changelog
[Changelog](CHANGELOG.md)
## License
[MIT](LICENSE)
[npm]: https://img.shields.io/npm/v/svelte-intersection-observer.svg?color=%23ff3e00&style=for-the-badge
[npm-url]: https://npmjs.com/package/svelte-intersection-observer