Skip to content
Source
Sign inSign up
TanStack/virtual
Open History to see the last commit

README.md

130 lines3.6 KB

1# Angular Virtual
2​
3Efficiently 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​
91. 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​
332. 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​
1113. 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 { injectVirtualizer } 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​
130For more examples and detailed usage, visit the [official documentation](https://tanstack.com/virtual/latest).