1 | [![Build Status](https://travis-ci.org/orizens/ngx-infinite-scroll.svg?branch=master)](https://travis-ci.org/orizens/ngx-infinite-scroll) [![Backers on Open Collective](https://opencollective.com/ngx-infinite-scroll/backers/badge.svg)](#backers) [![Sponsors on Open Collective](https://opencollective.com/ngx-infinite-scroll/sponsors/badge.svg)](#sponsors)
|
2 | [![npm version](https://badge.fury.io/js/ngx-infinite-scroll.svg)](https://badge.fury.io/js/ngx-infinite-scroll)
|
3 | [![npm version](https://badge.fury.io/js/ngx-infinite-scroll.svg)](https://badge.fury.io/js/ngx-infinite-scroll)
|
4 | [![npm downloads a month](https://img.shields.io/npm/dm/ngx-infinite-scroll.svg)](https://img.shields.io/npm/dm/ngx-infinite-scroll.svg)
|
5 | [![npm downloads a week](https://img.shields.io/npm/dt/ngx-infinite-scroll.svg)](https://img.shields.io/npm/dt/ngx-infinite-scroll.svg)
|
6 |
|
7 | ## [Consider Becoming a sponsor](https://opencollective.com/ngx-infinite-scroll#sponsor)
|
8 |
|
9 | # Angular Infinite Scroll
|
10 |
|
11 | versions now follow Angular's version to easily reflect compatibility.
|
12 | Meaning, for **Angular 10**, use `ngx-infinite-scroll @ ^10.0.0`
|
13 |
|
14 | ## Angular - Older Versions Support
|
15 |
|
16 | Starting **Angular 6 and Above** - `ngx-infinite-scroll@THE_VERSION.0.0`
|
17 | For **Angular 4** and **Angular = ^5.5.6** - use version `ngx-infinite-scroll@0.8.4`
|
18 | For **Angular 5.x** with **rxjs =<5.5.2** - use version `ngx-infinite-scroll@0.8.3`
|
19 | For Angular version **<= 2.3.1**, you can use `npm i angular2-infinite-scroll` (latest version is 0.3.42) - please notice **the angular2-infinite-scroll** package is deprecated
|
20 |
|
21 | ## Used By
|
22 |
|
23 | - [Google](https://google.com)
|
24 | - [Apple](https://apple.com)
|
25 | - [Amazon](https://amazon.com)
|
26 | - [Microsoft](https://microsoft.com)
|
27 | - [Disney](https://disney.com)
|
28 | - [Sap](https://sap.com/)
|
29 | - [Cisco](https://cisco.com/)
|
30 | - [Yandex](https://yandex.com)
|
31 | - [Ancestry](https://www.ancestry.com/)
|
32 |
|
33 | and much more.
|
34 |
|
35 | > _These analytics are made available via the awesome [Scarf](https://www.npmjs.com/package/@scarf/scarf) package analytics library_
|
36 |
|
37 | ## Front End Consulting Services
|
38 |
|
39 | I'm a Senior Front End Engineer & Consultant at [Orizens](https://orizens.com).
|
40 | My services include:
|
41 |
|
42 | - Angular/React/Javascript Consulting
|
43 | - Front End Architecture Consulting
|
44 | - Project Code Review
|
45 | - Project Development
|
46 |
|
47 | [Contact Here](http://orizens.com/contact)
|
48 |
|
49 | <a href="https://orizens.com" target="_blank">
|
50 | <img src="https://cloud.githubusercontent.com/assets/878660/23353771/d0adbd12-fcd6-11e6-96be-7a236f8819d9.png" alt="Webpack and Angular" width="20%"/>
|
51 | </a>
|
52 |
|
53 | ## Installation
|
54 |
|
55 | ```
|
56 | npm install ngx-infinite-scroll --save
|
57 | ```
|
58 |
|
59 | ## Supported API
|
60 |
|
61 | ### Properties
|
62 |
|
63 | | @Input() | Type | Required | Default | Description |
|
64 | | ------------------------ | -------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
65 | | infiniteScrollDistance | number | optional | 2 | the bottom percentage point of the scroll nob relatively to the infinite-scroll container (i.e, 2 (2 \* 10 = 20%) is event is triggered when 80% (100% - 20%) has been scrolled). if container.height is 900px, when the container is scrolled to or past the 720px, it will fire the scrolled event. |
|
66 | | infiniteScrollUpDistance | number | optional | 1.5 | should get a number |
|
67 | | infiniteScrollThrottle | number | optional | 150 | should get a number of **milliseconds** for throttle. The event will be triggered this many milliseconds after the user _stops_ scrolling. |
|
68 | | scrollWindow | boolean | optional | true | listens to the window scroll instead of the actual element scroll. this allows to invoke a callback function in the scope of the element while listenning to the window scroll. |
|
69 | | immediateCheck | boolean | optional | false | invokes the handler immediately to check if a scroll event has been already triggred when the page has been loaded (i.e. - when you refresh a page that has been scrolled) |
|
70 | | infiniteScrollDisabled | boolean | optional | false | doesn't invoke the handler if set to true |
|
71 | | horizontal | boolean | optional | false | sets the scroll to listen for horizontal events |
|
72 | | alwaysCallback | boolean | optional | false | instructs the scroller to always trigger events |
|
73 | | infiniteScrollContainer | string / HTMLElement | optional | null | should get a html element or css selector for a scrollable element; window or current element will be used if this attribute is empty. |
|
74 | | fromRoot | boolean | optional | false | if **infiniteScrollContainer** is set, this instructs the scroller to query the container selector from the root of the **document** object. |
|
75 |
|
76 | ### Events
|
77 |
|
78 | | @Output() | Type | Event Type | Required | Description |
|
79 | | ---------- | ------------ | -------------------- | -------- | ------------------------------------------------------------------------------- |
|
80 | | scrolled | EventEmitter | IInfiniteScrollEvent | optional | this will callback if the distance threshold has been reached on a scroll down. |
|
81 | | scrolledUp | EventEmitter | IInfiniteScrollEvent | optional | this will callback if the distance threshold has been reached on a scroll up. |
|
82 |
|
83 | ## Behavior
|
84 |
|
85 | By default, the directive listens to the **window scroll** event and invoked the callback.
|
86 | **To trigger the callback when the actual element is scrolled**, these settings should be configured:
|
87 |
|
88 | - [scrollWindow]="false"
|
89 | - set an explict css "height" value to the element
|
90 |
|
91 | ## DEMO
|
92 |
|
93 | [Try the Demo in StackBlitz](https://stackblitz.com/edit/ngx-infinite-scroll)
|
94 |
|
95 | ## Usage
|
96 |
|
97 | First, import the InfiniteScrollModule to your module:
|
98 |
|
99 | ```typescript
|
100 | import { NgModule } from '@angular/core';
|
101 | import { BrowserModule } from '@angular/platform-browser';
|
102 | import { InfiniteScrollModule } from 'ngx-infinite-scroll';
|
103 | import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
|
104 | import { AppComponent } from './app';
|
105 |
|
106 | @NgModule({
|
107 | imports: [BrowserModule, InfiniteScrollModule],
|
108 | declarations: [AppComponent],
|
109 | bootstrap: [AppComponent],
|
110 | })
|
111 | export class AppModule {}
|
112 |
|
113 | platformBrowserDynamic().bootstrapModule(AppModule);
|
114 | ```
|
115 |
|
116 | In this example, the **onScroll** callback will be invoked when the window is scrolled down:
|
117 |
|
118 | ```typescript
|
119 | import { Component } from '@angular/core';
|
120 |
|
121 | @Component({
|
122 | selector: 'app',
|
123 | template: `
|
124 | <div
|
125 | class="search-results"
|
126 | infiniteScroll
|
127 | [infiniteScrollDistance]="2"
|
128 | [infiniteScrollThrottle]="50"
|
129 | (scrolled)="onScroll()"
|
130 | ></div>
|
131 | `,
|
132 | })
|
133 | export class AppComponent {
|
134 | onScroll() {
|
135 | console.log('scrolled!!');
|
136 | }
|
137 | }
|
138 | ```
|
139 |
|
140 | in this example, whenever the "search-results" is scrolled, the callback will be invoked:
|
141 |
|
142 | ```typescript
|
143 | import { Component } from '@angular/core';
|
144 |
|
145 | @Component({
|
146 | selector: 'app',
|
147 | styles: [
|
148 | `
|
149 | .search-results {
|
150 | height: 20rem;
|
151 | overflow: scroll;
|
152 | }
|
153 | `,
|
154 | ],
|
155 | template: `
|
156 | <div
|
157 | class="search-results"
|
158 | infiniteScroll
|
159 | [infiniteScrollDistance]="2"
|
160 | [infiniteScrollThrottle]="50"
|
161 | (scrolled)="onScroll()"
|
162 | [scrollWindow]="false"
|
163 | ></div>
|
164 | `,
|
165 | })
|
166 | export class AppComponent {
|
167 | onScroll() {
|
168 | console.log('scrolled!!');
|
169 | }
|
170 | }
|
171 | ```
|
172 |
|
173 | In this example, the **onScrollDown** callback will be invoked when the window is scrolled down and the **onScrollUp** callback will be invoked when the window is scrolled up:
|
174 |
|
175 | ```typescript
|
176 | import { Component } from '@angular/core';
|
177 | import { InfiniteScroll } from 'ngx-infinite-scroll';
|
178 |
|
179 | @Component({
|
180 | selector: 'app',
|
181 | directives: [InfiniteScroll],
|
182 | template: `
|
183 | <div
|
184 | class="search-results"
|
185 | infiniteScroll
|
186 | [infiniteScrollDistance]="2"
|
187 | [infiniteScrollUpDistance]="1.5"
|
188 | [infiniteScrollThrottle]="50"
|
189 | (scrolled)="onScrollDown()"
|
190 | (scrolledUp)="onScrollUp()"
|
191 | ></div>
|
192 | `,
|
193 | })
|
194 | export class AppComponent {
|
195 | onScrollDown() {
|
196 | console.log('scrolled down!!');
|
197 | }
|
198 |
|
199 | onScrollUp() {
|
200 | console.log('scrolled up!!');
|
201 | }
|
202 | }
|
203 | ```
|
204 |
|
205 | In this example, the **infiniteScrollContainer** attribute is used to point directive to the scrollable container using a css selector. **fromRoot** is used to determine whether the scroll container has to be searched within the whole document (`[fromRoot]="true"`) or just inside the **infiniteScroll** directive (`[fromRoot]="false"`, default option).
|
206 |
|
207 | ```typescript
|
208 | import { Component } from '@angular/core';
|
209 |
|
210 | @Component({
|
211 | selector: 'app',
|
212 | styles: [
|
213 | `
|
214 | .main-panel {
|
215 | height: 100px;
|
216 | overflow-y: scroll;
|
217 | }
|
218 | `,
|
219 | ],
|
220 | template: `
|
221 | <div class="main-panel">
|
222 | <div
|
223 | infiniteScroll
|
224 | [infiniteScrollDistance]="2"
|
225 | [infiniteScrollThrottle]="50"
|
226 | [infiniteScrollContainer]="selector"
|
227 | [fromRoot]="true"
|
228 | (scrolled)="onScroll()"
|
229 | ></div>
|
230 | </div>
|
231 | `,
|
232 | })
|
233 | export class AppComponent {
|
234 | selector: string = '.main-panel';
|
235 |
|
236 | onScroll() {
|
237 | console.log('scrolled!!');
|
238 | }
|
239 | }
|
240 | ```
|
241 |
|
242 | It is also possible to use **infiniteScrollContainer** without additional variable by using single quotes inside double quotes:
|
243 |
|
244 | ```
|
245 | [infiniteScrollContainer]="'.main-panel'"
|
246 | ```
|
247 |
|
248 | # Showcase Examples
|
249 |
|
250 | - [Echoes Player - Developed with Angular, angular-cli and ngrx](http://orizens.github.io/echoes-player) ([github repo for echoes player](http://github.com/orizens/echoes-player))
|
251 |
|
252 | ## Contributors
|
253 |
|
254 | This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].
|
255 | <a href="graphs/contributors"><img src="https://opencollective.com/ngx-infinite-scroll/contributors.svg?width=890" /></a>
|
256 |
|
257 | ## Backers
|
258 |
|
259 | Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/ngx-infinite-scroll#backer)]
|
260 |
|
261 | <a href="https://opencollective.com/ngx-infinite-scroll#backers" target="_blank"><img src="https://opencollective.com/ngx-infinite-scroll/backers.svg?width=890"></a>
|
262 |
|
263 | ## Sponsors
|
264 |
|
265 | <a href="https://opencollective.com/ngx-infinite-scroll/sponsor/0/website" target="_blank"><img src="https://opencollective.com/ngx-infinite-scroll/sponsor/0/avatar.svg"></a>
|
266 | <a href="https://opencollective.com/ngx-infinite-scroll/sponsor/1/website" target="_blank"><img src="https://opencollective.com/ngx-infinite-scroll/sponsor/1/avatar.svg"></a>
|
267 | <a href="https://opencollective.com/ngx-infinite-scroll/sponsor/2/website" target="_blank"><img src="https://opencollective.com/ngx-infinite-scroll/sponsor/2/avatar.svg"></a>
|
268 | <a href="https://opencollective.com/ngx-infinite-scroll/sponsor/3/website" target="_blank"><img src="https://opencollective.com/ngx-infinite-scroll/sponsor/3/avatar.svg"></a>
|
269 | <a href="https://opencollective.com/ngx-infinite-scroll/sponsor/4/website" target="_blank"><img src="https://opencollective.com/ngx-infinite-scroll/sponsor/4/avatar.svg"></a>
|
270 | <a href="https://opencollective.com/ngx-infinite-scroll/sponsor/5/website" target="_blank"><img src="https://opencollective.com/ngx-infinite-scroll/sponsor/5/avatar.svg"></a>
|
271 | <a href="https://opencollective.com/ngx-infinite-scroll/sponsor/6/website" target="_blank"><img src="https://opencollective.com/ngx-infinite-scroll/sponsor/6/avatar.svg"></a>
|
272 | <a href="https://opencollective.com/ngx-infinite-scroll/sponsor/7/website" target="_blank"><img src="https://opencollective.com/ngx-infinite-scroll/sponsor/7/avatar.svg"></a>
|
273 | <a href="https://opencollective.com/ngx-infinite-scroll/sponsor/8/website" target="_blank"><img src="https://opencollective.com/ngx-infinite-scroll/sponsor/8/avatar.svg"></a>
|
274 | <a href="https://opencollective.com/ngx-infinite-scroll/sponsor/9/website" target="_blank"><img src="https://opencollective.com/ngx-infinite-scroll/sponsor/9/avatar.svg"></a>
|