@tanstack/angular-virtual 3.10.2 → 3.10.4

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.
Files changed (6) hide show
  1. package/README.md +130 -0
  2. package/build/README.md +130 -0
  3. package/build/index.d.ts +9 -0
  4. package/build/proxy.d.ts +4 -0
  5. package/build/types.d.ts +13 -0
  6. package/package.json +3 -5
package/README.md ADDED
@@ -0,0 +1,130 @@
1
+ # Angular Virtual
2
+
3
+ Efficiently virtualize only the visible DOM nodes within massive scrollable elements using Angular, while maintaining complete control over markup and styles.
4
+
5
+ # Quick Start
6
+
7
+ > NOTE: Angular Virtual requires Angular 17.
8
+
9
+ 1. Install `@tanstack/angular-virtual`
10
+
11
+ ```bash
12
+ $ npm i @tanstack/angular-virtual
13
+ ```
14
+
15
+ or
16
+
17
+ ```bash
18
+ $ pnpm add @tanstack/angular-virtual
19
+ ```
20
+
21
+ or
22
+
23
+ ```bash
24
+ $ yarn add @tanstack/angular-virtual
25
+ ```
26
+
27
+ or
28
+
29
+ ```bash
30
+ $ bun add @tanstack/angular-virtual
31
+ ```
32
+
33
+ 2. Inject a virtualizer
34
+
35
+ `@tanstack/angular-virtual` utilizes a helper function `injectVirtualizer` to create the virtualizer and integrate it with the component lifecycle:
36
+
37
+ ```ts
38
+ import { Component, ElementRef, viewChild } from '@angular/core'
39
+ import { injectVirtualizer } from '@tanstack/angular-virtual'
40
+
41
+ @Component({
42
+ selector: 'my-virtualized-list',
43
+ template: `
44
+ <div
45
+ #scrollElement
46
+ style="height: 400px; border: 1px solid gray; overflow: auto;"
47
+ >
48
+ <div
49
+ style="position: relative; width: 100%;"
50
+ [style.height.px]="virtualizer.getTotalSize()"
51
+ >
52
+ @for (row of virtualizer.getVirtualItems(); track row.index) {
53
+ <div
54
+ style="position: absolute; top: 0; left: 0; width: 100%; height: 35px"
55
+ [style.transform]="'translateY(' + row.start + 'px)'"
56
+ >
57
+ Row {{ row.index }}
58
+ </div>
59
+ }
60
+ </div>
61
+ </div>
62
+ `,
63
+ })
64
+ export class MyVirtualizedList {
65
+ scrollElement = viewChild<ElementRef<HTMLDivElement>>('scrollElement')
66
+
67
+ virtualizer = injectVirtualizer(() => ({
68
+ scrollElement: this.scrollElement(),
69
+ count: 1000,
70
+ estimateSize: () => 35,
71
+ overscan: 5,
72
+ }))
73
+ }
74
+ ```
75
+
76
+ Note that a [ViewChild](https://angular.dev/api/core/viewChild) is used to get a reference to the scrolling container to allow the virtualizer to interact with it. The adapter will automatically unwrap the [ElementRef](https://angular.dev/api/core/ElementRef) for you.
77
+
78
+ You can also create a virtualizer that attaches to the Window with `injectWindowVirtualizer`:
79
+
80
+ ```ts
81
+ import { Component } from '@angular/core'
82
+ import { injectWindowVirtualizer } from '@tanstack/angular-virtual'
83
+
84
+ @Component({
85
+ selector: 'my-window-virtualized-list',
86
+ template: `
87
+ <div
88
+ style="position: relative; width: 100%;"
89
+ [style.height.px]="virtualizer.getTotalSize()"
90
+ >
91
+ @for (row of virtualizer.getVirtualItems(); track row.index) {
92
+ <div
93
+ style="position: absolute; top: 0; left: 0; width: 100%; height: 35px"
94
+ [style.transform]="'translateY(' + row.start + 'px)'"
95
+ >
96
+ Row {{ row.index }}
97
+ </div>
98
+ }
99
+ </div>
100
+ `,
101
+ })
102
+ export class MyWindowVirtualizedList {
103
+ virtualizer = injectWindowVirtualizer(() => ({
104
+ count: 1000,
105
+ estimateSize: () => 35,
106
+ overscan: 5,
107
+ }))
108
+ }
109
+ ```
110
+
111
+ 3. If you need to update options on your virtualizer dynamically, make sure to use signals.
112
+
113
+ ```ts
114
+ import { Component, input } from '@angular/core'
115
+ import { injectWindowVirtualizer } from '@tanstack/angular-virtual'
116
+
117
+ @Component({...})
118
+ export class MyVirtualizedList {
119
+ items = input<Array<string>>()
120
+
121
+ virtualizer = injectVirtualizer(() => ({
122
+ scrollElement: this.scrollElement(),
123
+ count: this.items().length,
124
+ estimateSize: () => 35,
125
+ overscan: 5,
126
+ }))
127
+ }
128
+ ```
129
+
130
+ For more examples and detailed usage, visit the [official documentation](https://tanstack.com/virtual/latest).
package/build/README.md ADDED
@@ -0,0 +1,130 @@
1
+ # Angular Virtual
2
+
3
+ Efficiently virtualize only the visible DOM nodes within massive scrollable elements using Angular, while maintaining complete control over markup and styles.
4
+
5
+ # Quick Start
6
+
7
+ > NOTE: Angular Virtual requires Angular 17.
8
+
9
+ 1. Install `@tanstack/angular-virtual`
10
+
11
+ ```bash
12
+ $ npm i @tanstack/angular-virtual
13
+ ```
14
+
15
+ or
16
+
17
+ ```bash
18
+ $ pnpm add @tanstack/angular-virtual
19
+ ```
20
+
21
+ or
22
+
23
+ ```bash
24
+ $ yarn add @tanstack/angular-virtual
25
+ ```
26
+
27
+ or
28
+
29
+ ```bash
30
+ $ bun add @tanstack/angular-virtual
31
+ ```
32
+
33
+ 2. Inject a virtualizer
34
+
35
+ `@tanstack/angular-virtual` utilizes a helper function `injectVirtualizer` to create the virtualizer and integrate it with the component lifecycle:
36
+
37
+ ```ts
38
+ import { Component, ElementRef, viewChild } from '@angular/core'
39
+ import { injectVirtualizer } from '@tanstack/angular-virtual'
40
+
41
+ @Component({
42
+ selector: 'my-virtualized-list',
43
+ template: `
44
+ <div
45
+ #scrollElement
46
+ style="height: 400px; border: 1px solid gray; overflow: auto;"
47
+ >
48
+ <div
49
+ style="position: relative; width: 100%;"
50
+ [style.height.px]="virtualizer.getTotalSize()"
51
+ >
52
+ @for (row of virtualizer.getVirtualItems(); track row.index) {
53
+ <div
54
+ style="position: absolute; top: 0; left: 0; width: 100%; height: 35px"
55
+ [style.transform]="'translateY(' + row.start + 'px)'"
56
+ >
57
+ Row {{ row.index }}
58
+ </div>
59
+ }
60
+ </div>
61
+ </div>
62
+ `,
63
+ })
64
+ export class MyVirtualizedList {
65
+ scrollElement = viewChild<ElementRef<HTMLDivElement>>('scrollElement')
66
+
67
+ virtualizer = injectVirtualizer(() => ({
68
+ scrollElement: this.scrollElement(),
69
+ count: 1000,
70
+ estimateSize: () => 35,
71
+ overscan: 5,
72
+ }))
73
+ }
74
+ ```
75
+
76
+ Note that a [ViewChild](https://angular.dev/api/core/viewChild) is used to get a reference to the scrolling container to allow the virtualizer to interact with it. The adapter will automatically unwrap the [ElementRef](https://angular.dev/api/core/ElementRef) for you.
77
+
78
+ You can also create a virtualizer that attaches to the Window with `injectWindowVirtualizer`:
79
+
80
+ ```ts
81
+ import { Component } from '@angular/core'
82
+ import { injectWindowVirtualizer } from '@tanstack/angular-virtual'
83
+
84
+ @Component({
85
+ selector: 'my-window-virtualized-list',
86
+ template: `
87
+ <div
88
+ style="position: relative; width: 100%;"
89
+ [style.height.px]="virtualizer.getTotalSize()"
90
+ >
91
+ @for (row of virtualizer.getVirtualItems(); track row.index) {
92
+ <div
93
+ style="position: absolute; top: 0; left: 0; width: 100%; height: 35px"
94
+ [style.transform]="'translateY(' + row.start + 'px)'"
95
+ >
96
+ Row {{ row.index }}
97
+ </div>
98
+ }
99
+ </div>
100
+ `,
101
+ })
102
+ export class MyWindowVirtualizedList {
103
+ virtualizer = injectWindowVirtualizer(() => ({
104
+ count: 1000,
105
+ estimateSize: () => 35,
106
+ overscan: 5,
107
+ }))
108
+ }
109
+ ```
110
+
111
+ 3. If you need to update options on your virtualizer dynamically, make sure to use signals.
112
+
113
+ ```ts
114
+ import { Component, input } from '@angular/core'
115
+ import { injectWindowVirtualizer } from '@tanstack/angular-virtual'
116
+
117
+ @Component({...})
118
+ export class MyVirtualizedList {
119
+ items = input<Array<string>>()
120
+
121
+ virtualizer = injectVirtualizer(() => ({
122
+ scrollElement: this.scrollElement(),
123
+ count: this.items().length,
124
+ estimateSize: () => 35,
125
+ overscan: 5,
126
+ }))
127
+ }
128
+ ```
129
+
130
+ For more examples and detailed usage, visit the [official documentation](https://tanstack.com/virtual/latest).
package/build/index.d.ts ADDED
@@ -0,0 +1,9 @@
1
+ import { PartialKeys, VirtualizerOptions } from '@tanstack/virtual-core';
2
+ export * from '@tanstack/virtual-core';
3
+ export * from './types';
4
+ import { ElementRef } from '@angular/core';
5
+ import { AngularVirtualizer } from './types';
6
+ export declare function injectVirtualizer<TScrollElement extends Element, TItemElement extends Element>(options: () => PartialKeys<Omit<VirtualizerOptions<TScrollElement, TItemElement>, 'getScrollElement'>, 'observeElementRect' | 'observeElementOffset' | 'scrollToFn'> & {
7
+ scrollElement: ElementRef<TScrollElement> | TScrollElement | undefined;
8
+ }): AngularVirtualizer<TScrollElement, TItemElement>;
9
+ export declare function injectWindowVirtualizer<TItemElement extends Element>(options: () => PartialKeys<VirtualizerOptions<Window, TItemElement>, 'getScrollElement' | 'observeElementRect' | 'observeElementOffset' | 'scrollToFn'>): AngularVirtualizer<Window, TItemElement>;
package/build/proxy.d.ts ADDED
@@ -0,0 +1,4 @@
1
+ import { WritableSignal } from '@angular/core';
2
+ import { Virtualizer } from '@tanstack/virtual-core';
3
+ import { AngularVirtualizer } from './types';
4
+ export declare function proxyVirtualizer<V extends Virtualizer<any, any>, S extends Element | Window = V extends Virtualizer<infer U, any> ? U : never, I extends Element = V extends Virtualizer<any, infer U> ? U : never>(virtualizerSignal: WritableSignal<V>, lazyInit: () => V): AngularVirtualizer<S, I>;
package/build/types.d.ts ADDED
@@ -0,0 +1,13 @@
1
+ import { Signal } from '@angular/core';
2
+ import { Virtualizer } from '@tanstack/virtual-core';
3
+ export type AngularVirtualizer<TScrollElement extends Element | Window, TItemElement extends Element> = Omit<Virtualizer<TScrollElement, TItemElement>, 'getTotalSize' | 'getVirtualItems' | 'isScrolling' | 'options' | 'range' | 'scrollDirection' | 'scrollElement' | 'scrollOffset' | 'scrollRect'> & {
4
+ getTotalSize: Signal<ReturnType<Virtualizer<TScrollElement, TItemElement>['getTotalSize']>>;
5
+ getVirtualItems: Signal<ReturnType<Virtualizer<TScrollElement, TItemElement>['getVirtualItems']>>;
6
+ isScrolling: Signal<Virtualizer<TScrollElement, TItemElement>['isScrolling']>;
7
+ options: Signal<Virtualizer<TScrollElement, TItemElement>['options']>;
8
+ range: Signal<Virtualizer<TScrollElement, TItemElement>['range']>;
9
+ scrollDirection: Signal<Virtualizer<TScrollElement, TItemElement>['scrollDirection']>;
10
+ scrollElement: Signal<Virtualizer<TScrollElement, TItemElement>['scrollElement']>;
11
+ scrollOffset: Signal<Virtualizer<TScrollElement, TItemElement>['scrollOffset']>;
12
+ scrollRect: Signal<Virtualizer<TScrollElement, TItemElement>['scrollRect']>;
13
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tanstack/angular-virtual",
3
- "version": "3.10.2",
3
+ "version": "3.10.4",
4
4
  "description": "Headless UI for virtualizing scrollable elements in Angular",
5
5
  "author": "Garrett Darnell",
6
6
  "license": "MIT",
@@ -37,13 +37,11 @@
37
37
  "node": ">=12"
38
38
  },
39
39
  "files": [
40
- "build",
41
- "!**/*.d.ts",
42
- "!**/*.d.ts.map"
40
+ "build"
43
41
  ],
44
42
  "dependencies": {
45
43
  "tslib": "^2.6.3",
46
- "@tanstack/virtual-core": "3.10.2"
44
+ "@tanstack/virtual-core": "3.10.4"
47
45
  },
48
46
  "devDependencies": {
49
47
  "@angular/core": "^17.3.0",