├── .github
└── workflows
│ ├── ci.yml
│ └── release.yml
├── .gitignore
├── CHANGELOG.md
├── LICENSE
├── README.md
├── bun.lock
├── package.json
├── playwright.config.ts
├── playwright
├── index.html
└── index.js
├── rollup.config.ts
├── scripts
└── npm-package.ts
├── src
├── IntersectionObserver.svelte
├── IntersectionObserver.svelte.d.ts
├── index.d.ts
└── index.js
├── tests
├── Basic.svelte
├── IntersectionObserver.test.svelte
├── IntersectionObserver.test.ts
├── Once.svelte
└── RootMargin.svelte
└── tsconfig.json
/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
1 | on:
2 | pull_request:
3 | push:
4 | branches: [master]
5 |
6 | jobs:
7 | test:
8 | runs-on: macos-latest
9 | steps:
10 | - uses: actions/checkout@v4
11 | - uses: oven-sh/setup-bun@v2
12 | - uses: actions/cache@v4
13 | id: playwright-cache
14 | with:
15 | path: /Users/runner/Library/Caches/ms-playwright
16 | key: ${{ runner.os }}-playwright-${{ hashFiles('**/bun.lock') }}
17 |
18 | - name: Install dependencies
19 | run: bun install
20 |
21 | - name: Install Playwright binaries
22 | run: bunx playwright install --with-deps
23 | if: steps.playwright-cache.outputs.cache-hit != 'true'
24 |
25 | - name: Run unit tests
26 | run: bun run test:types
27 |
28 | - name: Run e2e tests
29 | run: bun run test:e2e
30 |
31 | - name: Build docs
32 | if: github.ref == 'refs/heads/master'
33 | run: bun run build
34 |
35 | - name: Deploy docs
36 | if: github.ref == 'refs/heads/master'
37 | uses: peaceiris/actions-gh-pages@v4
38 | with:
39 | github_token: ${{ secrets.GITHUB_TOKEN }}
40 | publish_dir: dist
41 |
--------------------------------------------------------------------------------
/.github/workflows/release.yml:
--------------------------------------------------------------------------------
1 | on:
2 | push:
3 | tags:
4 | - "v*"
5 |
6 | jobs:
7 | build:
8 | runs-on: ubuntu-latest
9 | permissions:
10 | contents: read
11 | id-token: write
12 | steps:
13 | - uses: actions/checkout@v4
14 | - uses: oven-sh/setup-bun@v2
15 | - uses: actions/setup-node@v4
16 | with:
17 | node-version: "20.x"
18 | registry-url: "https://registry.npmjs.org"
19 |
20 | - name: Build package
21 | run: bun run package
22 |
23 | - name: Publish package
24 | env:
25 | NODE_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}
26 |
27 | # Currently, only npm supports publishing packages with provenance
28 | # https://docs.npmjs.com/generating-provenance-statements
29 | run: |
30 | cd package
31 | npm publish --provenance --access public
32 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | .DS_Store
2 | /dist
3 | /node_modules
4 | /test-results/
5 | /playwright-report/
6 | /playwright/.cache/
7 | /package
--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
1 | # Changelog
2 |
3 | All notable changes to this project will be documented in this file.
4 |
5 | The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6 | and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7 |
8 | ## [1.0.0](https://github.com/metonym/svelte-intersection-observer/releases/tag/v1.0.0) - 2024-01-01
9 |
10 | **Breaking Changes**
11 |
12 | - Remove `IntersectionObserverProps` or `Entry` TypeScript interfaces from `IntersectionObserver.svelte.d.ts`
13 | - Drop support for bundled ESM/UMD; code is only distributed as Svelte files
14 |
15 | **Fixes**
16 |
17 | - `element` and `root` prop types should be `null | HTMLElement` to support TypeScript strict mode
18 | - Add `exports` field to `package.json`
19 |
20 | ## [0.10.2](https://github.com/metonym/svelte-intersection-observer/releases/tag/v0.10.2) - 2024-01-01
21 |
22 | **Fixes**
23 |
24 | - Add `exports` field to `package.json`
25 |
26 | ## [0.10.1](https://github.com/metonym/svelte-intersection-observer/releases/tag/v0.10.1) - 2023-07-20
27 |
28 | **Fixes**
29 |
30 | - Fix `threshold` prop type to be `number | number[]`
31 |
32 | ## [0.10.0](https://github.com/metonym/svelte-intersection-observer/releases/tag/v0.10.0) - 2021-12-29
33 |
34 | **Features**
35 |
36 | - Mark `observer` for garbage collection after disconnecting
37 |
38 | **Documentation**
39 |
40 | - Make prop descriptions consistent with docs
41 |
42 | **Refactoring**
43 |
44 | - Omit redundant `null` from `element` and `root` types as `HTMLElement` is already nullable
45 |
46 | ## [0.9.2](https://github.com/metonym/svelte-intersection-observer/releases/tag/v0.9.2) - 2021-11-26
47 |
48 | **Documentation**
49 |
50 | - Add `let:` directive example
51 | - Update component prop descriptions
52 | - Use Svelte syntax highlighting for `on:observe`, `on:intersect` examples
53 |
54 | ## [0.9.1](https://github.com/metonym/svelte-intersection-observer/releases/tag/v0.9.1) - 2021-10-25
55 |
56 | **Documentation**
57 |
58 | - Update the "Once" example to include the `"svelte-intersection-observer"` import
59 | - Rename example `svite` to `vite`
60 |
61 | **Refactoring**
62 |
63 | - Inline `entry` prop typedef
64 | - Remove `@event`, `@slot` artifacts used by sveld to generate initial TypeScript definitions
65 |
66 | ## [0.9.0](https://github.com/metonym/svelte-intersection-observer/releases/tag/v0.9.0) - 2021-10-05
67 |
68 | - Improve TypeScript definitions for dispatched events
69 | - `on:observe`: `event.detail.isIntersecting` is a `boolean`
70 | - `on:intersect`: `event.detail.isIntersecting` can only be `true`
71 |
72 | ## [0.8.0](https://github.com/metonym/svelte-intersection-observer/releases/tag/v0.8.0) - 2021-09-02
73 |
74 | - Use `.svelte.d.ts` extension for component TypeScript definition
75 |
76 | ## [0.7.1](https://github.com/metonym/svelte-intersection-observer/releases/tag/v0.7.1) - 2021-07-05
77 |
78 | **Documentation**
79 |
80 | - Add description for basic usage
81 | - Add `on:observe` example
82 | - Explain difference between `on:observe` and `on:intersect`
83 | - Document `IntersectionObserverEntry` interface
84 | - Re-order prop table so that `once` and `intersecting` are more prominent
85 |
86 | ## [0.7.0](https://github.com/metonym/svelte-intersection-observer/releases/tag/v0.7.0) - 2021-04-23
87 |
88 | **Features**
89 |
90 | - Re-initialize observer if `rootMargin` changes
91 |
92 | ## [0.6.1](https://github.com/metonym/svelte-intersection-observer/releases/tag/v0.6.1) - 2021-04-03
93 |
94 | **Fixes**
95 |
96 | - Move intersection observer instantiation to `onMount` to work in hydration use cases
97 |
98 | ## [0.6.0](https://github.com/metonym/svelte-intersection-observer/releases/tag/v0.6.0) - 2021-02-24
99 |
100 | **Features**
101 |
102 | - Export `observer` prop (type `IntersectionObserver`)
103 | - Dispatch "intersect" event if the observed element `isIntersecting` the viewport
104 |
105 | ## [0.5.0](https://github.com/metonym/svelte-intersection-observer/releases/tag/v0.5.0) - 2021-01-20
106 |
107 | **Features**
108 |
109 | - Add support for Server-Side Rendering (SSR)
110 |
111 | ## [0.4.0](https://github.com/metonym/svelte-intersection-observer/releases/tag/v0.4.0) - 2020-12-20
112 |
113 | **Features**
114 |
115 | - Export `intersecting` prop
116 |
117 | **Fixes**
118 |
119 | - Remove observer from module context to allow multiple component instantiations
120 | - Fix prop type for `entry`
121 |
122 | ## [0.3.0](https://github.com/metonym/svelte-intersection-observer/releases/tag/v0.3.0) - 2020-11-23
123 |
124 | - Export `entry` as a reactive prop
125 |
126 | ## [0.2.0](https://github.com/metonym/svelte-intersection-observer/releases/tag/v0.2.0) - 2020-11-18
127 |
128 | - Add TypeScript definitions
129 |
130 | ## [0.1.1](https://github.com/metonym/svelte-intersection-observer/releases/tag/v0.1.1) - 2020-04-05
131 |
132 | - Only `disconnect` observer in `onDestroy` lifecycle method
133 |
134 | ## [0.1.0](https://github.com/metonym/svelte-intersection-observer/releases/tag/v0.1.0) - 2020-04-05
135 |
136 | - Initial release
137 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2020-present Eric Liu
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # svelte-intersection-observer
2 |
3 | [![NPM][npm]][npm-url]
4 |
5 | > 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).
6 |
7 |
8 |
9 | Try it in the [Svelte REPL](https://svelte.dev/repl/8cd2327a580c4f429c71f7df999bd51d).
10 |
11 |
12 |
13 | ## Installation
14 |
15 | ```sh
16 | # NPM
17 | npm i svelte-intersection-observer
18 |
19 | # pnpm
20 | pnpm i svelte-intersection-observer
21 |
22 | # Bun
23 | bun i svelte-intersection-observer
24 |
25 | # Yarn
26 | yarn add svelte-intersection-observer
27 |
28 | ```
29 |
30 | ## Usage
31 |
32 | ### Basic
33 |
34 | Use the [`bind:this`](https://svelte.dev/docs#bind_element) directive to pass an element reference to the `IntersectionObserver` component.
35 |
36 | Then, simply bind to the reactive `intersecting` prop to determine if the element intersects the viewport.
37 |
38 | ```svelte
39 |
45 |
46 |
47 | {intersecting ? "Element is in view" : "Element is not in view"}
48 |
49 |
50 |
51 |
Hello world
52 |
53 | ```
54 |
55 | ### Once
56 |
57 | Set `once` to `true` for the intersection event to occur only once. The `element` will be unobserved after the first intersection event occurs.
58 |
59 | ```svelte
60 |
66 |
67 |
68 | {intersectOnce ? "Element is in view" : "Element is not in view"}
69 |
70 |
71 |
76 |
Hello world
77 |
78 | ```
79 |
80 | ### `let:intersecting`
81 |
82 | An alternative to binding to the `intersecting` prop is to use the `let:` directive.
83 |
84 | In the following example, the "Hello world" element will fade in when its containing element intersects the viewport.
85 |
86 | ```svelte
87 |
93 |
94 |
95 |
96 |
97 |
98 | {#if intersecting}
99 |
Hello world
100 | {/if}
101 |
102 |
103 | ```
104 |
105 | ### `on:observe` event
106 |
107 | The `observe` event is dispatched when the element is first observed and also whenever an intersection event occurs.
108 |
109 | ```svelte no-eval
110 | {
113 | console.log(e.detail); // IntersectionObserverEntry
114 | console.log(e.detail.isIntersecting); // true | false
115 | }}
116 | >
117 |
Hello world
118 |
119 | ```
120 |
121 | ### `on:intersect` event
122 |
123 | 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.
124 |
125 | **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`.
126 |
127 | ```svelte no-eval
128 | {
131 | console.log(e.detail); // IntersectionObserverEntry
132 | console.log(e.detail.isIntersecting); // true
133 | }}
134 | >
135 |