@su-labs/scroll-spy 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +98 -0
- package/fesm2022/su-labs-scroll-spy.mjs +84 -0
- package/fesm2022/su-labs-scroll-spy.mjs.map +1 -0
- package/index.d.ts +32 -0
- package/package.json +51 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Yevheniy Alekseyev <yev.alekseyev@gmail.com>
|
|
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.
|
package/README.md
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# ScrollSpy
|
|
2
|
+
|
|
3
|
+
A lightweight Angular service and directive for managing active sections based on scroll position. Easily track which section of a page is currently visible and update your UI accordingly. Perfect for navigation menus, table of contents, or one-page scroll applications.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
- Track the currently visible section on the page
|
|
8
|
+
- Reactive Signals for seamless integration with Angular
|
|
9
|
+
- Works with multiple sections
|
|
10
|
+
- Optional directive to automatically update the active section using IntersectionObserver
|
|
11
|
+
- Fully modular: use the service alone, or combine with the directive for automatic detection
|
|
12
|
+
|
|
13
|
+
## Installation
|
|
14
|
+
|
|
15
|
+
You can install this library via npm:
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
npm install @su-labs/scroll-spy
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Peer Dependencies
|
|
22
|
+
|
|
23
|
+
This library requires the following peer dependencies:
|
|
24
|
+
|
|
25
|
+
```txt
|
|
26
|
+
@angular/common: >=20.1.0
|
|
27
|
+
@angular/core: >=20.1.0
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Usage
|
|
31
|
+
|
|
32
|
+
### Using the service and directive
|
|
33
|
+
|
|
34
|
+
The most common usage is to combine the `ScrollSpyService` with the `ScrollSpyDirective` to create an automatic, reactive scroll-spy solution.
|
|
35
|
+
|
|
36
|
+
#### Attach the directive to your sections
|
|
37
|
+
|
|
38
|
+
In your component template, apply the `appScrollSpy` directive to each section you want to track. The input value should be a unique ID for that section. It's a good practice to also set the `id` attribute for anchor links.
|
|
39
|
+
|
|
40
|
+
```html
|
|
41
|
+
@for (section of sections; track section.id) {
|
|
42
|
+
<a
|
|
43
|
+
[href]="'#' + section.id"
|
|
44
|
+
[class.active]="activeSection() === section.id"
|
|
45
|
+
>
|
|
46
|
+
{{ section.name }}
|
|
47
|
+
</a>
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
@for (section of sections; track section.id) {
|
|
51
|
+
<section [id]="section.id" [appScrollSpy]="section.id">
|
|
52
|
+
<h2>{{ section.name }}</h2>
|
|
53
|
+
<p>Content for the {{ section.name }} section...</p>
|
|
54
|
+
</section>
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
#### Inject the service into your component
|
|
59
|
+
|
|
60
|
+
Because the `ScrollSpyService` is provided at the root level, you can simply inject it into any component. Directly assign the `activeSection` signal to a property to use it in your template.
|
|
61
|
+
|
|
62
|
+
```ts
|
|
63
|
+
import { Component, inject, signal } from '@angular/core';
|
|
64
|
+
import { ScrollSpyService, ScrollSpyDirective } from '@su-labs/scroll-spy';
|
|
65
|
+
import { NgClass } from '@angular/common';
|
|
66
|
+
|
|
67
|
+
@Component({
|
|
68
|
+
selector: 'app-scroll-example',
|
|
69
|
+
templateUrl: './scroll-example.component.html',
|
|
70
|
+
standalone: true,
|
|
71
|
+
imports: [ScrollSpyDirective, NgClass]
|
|
72
|
+
})
|
|
73
|
+
export class ScrollExampleComponent {
|
|
74
|
+
private readonly scrollSpyService = inject(ScrollSpyService);
|
|
75
|
+
activeSection = this.scrollSpyService.activeSection;
|
|
76
|
+
|
|
77
|
+
sections = [
|
|
78
|
+
{ id: 'home', name: 'Home' },
|
|
79
|
+
{ id: 'about', name: 'About' },
|
|
80
|
+
{ id: 'services', name: 'Services' },
|
|
81
|
+
{ id: 'contact', name: 'Contact' }
|
|
82
|
+
];
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## How It Works
|
|
87
|
+
|
|
88
|
+
The `ScrollSpyDirective` uses the browser's native [IntersectionObserver API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) to efficiently monitor when elements enter or exit the viewport. It's configured to trigger when a tracked section is roughly in the vertical center of the screen, providing a smooth and accurate "spy" effect.
|
|
89
|
+
|
|
90
|
+
## Contributing
|
|
91
|
+
|
|
92
|
+
If you find any bugs or have feature requests, please open an issue or submit a pull request on our [**GitHub repository**](https://github.com/Greezaaa/settings-utils-lib.git).
|
|
93
|
+
|
|
94
|
+
To contribute code, please ensure your changes include unit tests to maintain code quality. Please see the main repository's `README.md` for details on the monorepo structure.
|
|
95
|
+
|
|
96
|
+
## License
|
|
97
|
+
|
|
98
|
+
This project is licensed under the MIT License. See the [**LICENSE**](https://github.com/Greezaaa/settings-utils-lib/blob/main/LICENSE) file for details.
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
import * as i0 from '@angular/core';
|
|
2
|
+
import { signal, Injectable, inject, ElementRef, Input, Directive } from '@angular/core';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Service that keeps track of the currently active section while scrolling.
|
|
6
|
+
* Can be injected into components to react to section changes.
|
|
7
|
+
*/
|
|
8
|
+
class ScrollSpyService {
|
|
9
|
+
/** ID of the currently visible section */
|
|
10
|
+
activeSection = signal('', ...(ngDevMode ? [{ debugName: "activeSection" }] : []));
|
|
11
|
+
static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.1.7", ngImport: i0, type: ScrollSpyService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
|
|
12
|
+
static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.1.7", ngImport: i0, type: ScrollSpyService, providedIn: 'root' });
|
|
13
|
+
}
|
|
14
|
+
i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.1.7", ngImport: i0, type: ScrollSpyService, decorators: [{
|
|
15
|
+
type: Injectable,
|
|
16
|
+
args: [{ providedIn: 'root' }]
|
|
17
|
+
}] });
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* Directive that observes an element's visibility on the screen
|
|
21
|
+
* and updates ScrollSpyService.activeSection when it enters the viewport.
|
|
22
|
+
*
|
|
23
|
+
* Usage:
|
|
24
|
+
* <section [appScrollSpy]="'home'">...</section>
|
|
25
|
+
*/
|
|
26
|
+
class ScrollSpyDirective {
|
|
27
|
+
/** ID of the observed section */
|
|
28
|
+
sectionId;
|
|
29
|
+
el = inject(ElementRef);
|
|
30
|
+
scrollSpy = inject(ScrollSpyService);
|
|
31
|
+
ngOnInit() {
|
|
32
|
+
const observer = new IntersectionObserver((entries) => {
|
|
33
|
+
for (const entry of entries) {
|
|
34
|
+
if (entry.isIntersecting) {
|
|
35
|
+
this.scrollSpy.activeSection.set(this.sectionId);
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
}, {
|
|
39
|
+
// The viewport used to check visibility.
|
|
40
|
+
// `null` means the browser viewport is used.
|
|
41
|
+
root: null,
|
|
42
|
+
// How much of the element needs to be visible to trigger the observer.
|
|
43
|
+
// `0` means it triggers as soon as even one pixel is visible within the root + rootMargin.
|
|
44
|
+
threshold: 0,
|
|
45
|
+
// rootMargin defines an offset around the viewport that affects when the observer triggers.
|
|
46
|
+
// Format: 'top right bottom left'
|
|
47
|
+
// In this case:
|
|
48
|
+
// - top: -50%
|
|
49
|
+
// - right: 0px
|
|
50
|
+
// - bottom: -50%
|
|
51
|
+
// - left: 0px
|
|
52
|
+
//
|
|
53
|
+
// This means the observer will consider the element "intersecting" only when
|
|
54
|
+
// it is roughly in the vertical center of the viewport.
|
|
55
|
+
// It's perfect for scroll-spy behavior, because it triggers when the section
|
|
56
|
+
// is the main focus on the screen, rather than just appearing at the top.
|
|
57
|
+
rootMargin: '-50% 0px -50% 0px',
|
|
58
|
+
});
|
|
59
|
+
observer.observe(this.el.nativeElement);
|
|
60
|
+
}
|
|
61
|
+
static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.1.7", ngImport: i0, type: ScrollSpyDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive });
|
|
62
|
+
static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "20.1.7", type: ScrollSpyDirective, isStandalone: true, selector: "[appScrollSpy]", inputs: { sectionId: ["appScrollSpy", "sectionId"] }, ngImport: i0 });
|
|
63
|
+
}
|
|
64
|
+
i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.1.7", ngImport: i0, type: ScrollSpyDirective, decorators: [{
|
|
65
|
+
type: Directive,
|
|
66
|
+
args: [{
|
|
67
|
+
selector: '[appScrollSpy]',
|
|
68
|
+
standalone: true,
|
|
69
|
+
}]
|
|
70
|
+
}], propDecorators: { sectionId: [{
|
|
71
|
+
type: Input,
|
|
72
|
+
args: ['appScrollSpy']
|
|
73
|
+
}] } });
|
|
74
|
+
|
|
75
|
+
/*
|
|
76
|
+
* Public API Surface of scroll-spy
|
|
77
|
+
*/
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* Generated bundle index. Do not edit.
|
|
81
|
+
*/
|
|
82
|
+
|
|
83
|
+
export { ScrollSpyDirective, ScrollSpyService };
|
|
84
|
+
//# sourceMappingURL=su-labs-scroll-spy.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"su-labs-scroll-spy.mjs","sources":["../../../../projects/su-labs/scroll-spy/src/lib/scroll-spy.service.ts","../../../../projects/su-labs/scroll-spy/src/lib/scroll-spy.directive.ts","../../../../projects/su-labs/scroll-spy/src/public-api.ts","../../../../projects/su-labs/scroll-spy/src/su-labs-scroll-spy.ts"],"sourcesContent":["import { Injectable, signal } from '@angular/core';\n\n/**\n * Service that keeps track of the currently active section while scrolling.\n * Can be injected into components to react to section changes.\n */\n@Injectable({ providedIn: 'root' })\nexport class ScrollSpyService {\n /** ID of the currently visible section */\n activeSection = signal<string>('');\n}\n","import { Directive, ElementRef, inject, Input, OnInit } from '@angular/core';\nimport { ScrollSpyService } from './scroll-spy.service';\n\n/**\n * Directive that observes an element's visibility on the screen\n * and updates ScrollSpyService.activeSection when it enters the viewport.\n *\n * Usage:\n * <section [appScrollSpy]=\"'home'\">...</section>\n */\n@Directive({\n selector: '[appScrollSpy]',\n standalone: true,\n})\nexport class ScrollSpyDirective implements OnInit {\n /** ID of the observed section */\n @Input('appScrollSpy') sectionId!: string;\n\n private readonly el = inject(ElementRef);\n private readonly scrollSpy = inject(ScrollSpyService);\n\n ngOnInit() {\n const observer = new IntersectionObserver(\n (entries) => {\n for (const entry of entries) {\n if (entry.isIntersecting) {\n this.scrollSpy.activeSection.set(this.sectionId);\n }\n }\n },\n {\n // The viewport used to check visibility.\n // `null` means the browser viewport is used.\n root: null,\n // How much of the element needs to be visible to trigger the observer.\n // `0` means it triggers as soon as even one pixel is visible within the root + rootMargin.\n threshold: 0,\n // rootMargin defines an offset around the viewport that affects when the observer triggers.\n // Format: 'top right bottom left'\n // In this case:\n // - top: -50%\n // - right: 0px\n // - bottom: -50%\n // - left: 0px\n //\n // This means the observer will consider the element \"intersecting\" only when\n // it is roughly in the vertical center of the viewport.\n // It's perfect for scroll-spy behavior, because it triggers when the section\n // is the main focus on the screen, rather than just appearing at the top.\n rootMargin: '-50% 0px -50% 0px',\n },\n );\n observer.observe(this.el.nativeElement);\n }\n}\n","/*\n * Public API Surface of scroll-spy\n */\n\nexport * from './lib/scroll-spy.service';\nexport * from './lib/scroll-spy.directive';\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './public-api';\n"],"names":[],"mappings":";;;AAEA;;;AAGG;MAEU,gBAAgB,CAAA;;AAE3B,IAAA,aAAa,GAAG,MAAM,CAAS,EAAE,yDAAC;uGAFvB,gBAAgB,EAAA,IAAA,EAAA,EAAA,EAAA,MAAA,EAAA,EAAA,CAAA,eAAA,CAAA,UAAA,EAAA,CAAA;AAAhB,IAAA,OAAA,KAAA,GAAA,EAAA,CAAA,qBAAA,CAAA,EAAA,UAAA,EAAA,QAAA,EAAA,OAAA,EAAA,QAAA,EAAA,QAAA,EAAA,EAAA,EAAA,IAAA,EAAA,gBAAgB,cADH,MAAM,EAAA,CAAA;;2FACnB,gBAAgB,EAAA,UAAA,EAAA,CAAA;kBAD5B,UAAU;mBAAC,EAAE,UAAU,EAAE,MAAM,EAAE;;;ACHlC;;;;;;AAMG;MAKU,kBAAkB,CAAA;;AAEN,IAAA,SAAS;AAEf,IAAA,EAAE,GAAG,MAAM,CAAC,UAAU,CAAC;AACvB,IAAA,SAAS,GAAG,MAAM,CAAC,gBAAgB,CAAC;IAErD,QAAQ,GAAA;QACN,MAAM,QAAQ,GAAG,IAAI,oBAAoB,CACvC,CAAC,OAAO,KAAI;AACV,YAAA,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE;AAC3B,gBAAA,IAAI,KAAK,CAAC,cAAc,EAAE;oBACxB,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;;;AAGtD,SAAC,EACD;;;AAGE,YAAA,IAAI,EAAE,IAAI;;;AAGV,YAAA,SAAS,EAAE,CAAC;;;;;;;;;;;;;AAaZ,YAAA,UAAU,EAAE,mBAAmB;AAChC,SAAA,CACF;QACD,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,aAAa,CAAC;;uGAtC9B,kBAAkB,EAAA,IAAA,EAAA,EAAA,EAAA,MAAA,EAAA,EAAA,CAAA,eAAA,CAAA,SAAA,EAAA,CAAA;2FAAlB,kBAAkB,EAAA,YAAA,EAAA,IAAA,EAAA,QAAA,EAAA,gBAAA,EAAA,MAAA,EAAA,EAAA,SAAA,EAAA,CAAA,cAAA,EAAA,WAAA,CAAA,EAAA,EAAA,QAAA,EAAA,EAAA,EAAA,CAAA;;2FAAlB,kBAAkB,EAAA,UAAA,EAAA,CAAA;kBAJ9B,SAAS;AAAC,YAAA,IAAA,EAAA,CAAA;AACT,oBAAA,QAAQ,EAAE,gBAAgB;AAC1B,oBAAA,UAAU,EAAE,IAAI;AACjB,iBAAA;8BAGwB,SAAS,EAAA,CAAA;sBAA/B,KAAK;uBAAC,cAAc;;;AChBvB;;AAEG;;ACFH;;AAEG;;;;"}
|
package/index.d.ts
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import * as i0 from '@angular/core';
|
|
2
|
+
import { OnInit } from '@angular/core';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Service that keeps track of the currently active section while scrolling.
|
|
6
|
+
* Can be injected into components to react to section changes.
|
|
7
|
+
*/
|
|
8
|
+
declare class ScrollSpyService {
|
|
9
|
+
/** ID of the currently visible section */
|
|
10
|
+
activeSection: i0.WritableSignal<string>;
|
|
11
|
+
static ɵfac: i0.ɵɵFactoryDeclaration<ScrollSpyService, never>;
|
|
12
|
+
static ɵprov: i0.ɵɵInjectableDeclaration<ScrollSpyService>;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* Directive that observes an element's visibility on the screen
|
|
17
|
+
* and updates ScrollSpyService.activeSection when it enters the viewport.
|
|
18
|
+
*
|
|
19
|
+
* Usage:
|
|
20
|
+
* <section [appScrollSpy]="'home'">...</section>
|
|
21
|
+
*/
|
|
22
|
+
declare class ScrollSpyDirective implements OnInit {
|
|
23
|
+
/** ID of the observed section */
|
|
24
|
+
sectionId: string;
|
|
25
|
+
private readonly el;
|
|
26
|
+
private readonly scrollSpy;
|
|
27
|
+
ngOnInit(): void;
|
|
28
|
+
static ɵfac: i0.ɵɵFactoryDeclaration<ScrollSpyDirective, never>;
|
|
29
|
+
static ɵdir: i0.ɵɵDirectiveDeclaration<ScrollSpyDirective, "[appScrollSpy]", never, { "sectionId": { "alias": "appScrollSpy"; "required": false; }; }, {}, never, never, true, never>;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export { ScrollSpyDirective, ScrollSpyService };
|
package/package.json
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@su-labs/scroll-spy",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "An Angular scroll spy utility based on IntersectionObserver for tracking active sections or menu items.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"angular",
|
|
7
|
+
"scroll-spy",
|
|
8
|
+
"intersection-observer",
|
|
9
|
+
"section-spy",
|
|
10
|
+
"menu-spy",
|
|
11
|
+
"active-section",
|
|
12
|
+
"scroll",
|
|
13
|
+
"directive",
|
|
14
|
+
"utility",
|
|
15
|
+
"ui"
|
|
16
|
+
],
|
|
17
|
+
"author": {
|
|
18
|
+
"name": "Yevheniy Alekseyev",
|
|
19
|
+
"email": "yev.alekseyev@gmail.com",
|
|
20
|
+
"url": "https://github.com/Greezaaa"
|
|
21
|
+
},
|
|
22
|
+
"license": "MIT",
|
|
23
|
+
"repository": {
|
|
24
|
+
"type": "git",
|
|
25
|
+
"url": "git+https://github.com/Greezaaa/settings-utils-lib.git",
|
|
26
|
+
"directory": "projects/su-labs/scroll-spy"
|
|
27
|
+
},
|
|
28
|
+
"homepage": "https://github.com/Greezaaa/settings-utils-lib/tree/main/projects/su-labs/scroll-spy#readme",
|
|
29
|
+
"bugs": {
|
|
30
|
+
"url": "https://github.com/Greezaaa/settings-utils-lib/issues"
|
|
31
|
+
},
|
|
32
|
+
"peerDependencies": {
|
|
33
|
+
"@angular/common": "^20.1.0",
|
|
34
|
+
"@angular/core": "^20.1.0"
|
|
35
|
+
},
|
|
36
|
+
"dependencies": {
|
|
37
|
+
"tslib": "^2.3.0"
|
|
38
|
+
},
|
|
39
|
+
"sideEffects": false,
|
|
40
|
+
"module": "fesm2022/su-labs-scroll-spy.mjs",
|
|
41
|
+
"typings": "index.d.ts",
|
|
42
|
+
"exports": {
|
|
43
|
+
"./package.json": {
|
|
44
|
+
"default": "./package.json"
|
|
45
|
+
},
|
|
46
|
+
".": {
|
|
47
|
+
"types": "./index.d.ts",
|
|
48
|
+
"default": "./fesm2022/su-labs-scroll-spy.mjs"
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
}
|