Virtual List
Efficient rendering of large lists by only rendering visible items.
Basic Setup
javascript
import { list } from "@inglorious/web/list"
const productList = {
...list,
renderItem(item, index) {
return html`
<div class="product">
${index}: <strong>${item.name}</strong> — $${item.price}
</div>
`
},
}
const types = {
productList,
}
const entities = {
products: {
type: "productList",
items: Array.from({ length: 10000 }, (_, i) => ({
name: `Product ${i}`,
price: Math.random() * 100,
})),
viewportHeight: 400,
estimatedHeight: 40,
bufferSize: 5,
},
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
Configuration
javascript
{
type: 'list',
items: [], // Data to render
viewportHeight: 400, // Height of scrolling container
itemHeight: null, // Fixed height (auto-measure if null)
estimatedHeight: 40, // Fallback estimate
bufferSize: 5, // Extra items to render before/after visible
visibleRange: { start: 0, end: 10 }, // Current visible range
}
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
Events
javascript
// On scroll
api.notify("#list:scroll", scrollContainerElement)
// Measure item height
api.notify("#list:measureHeight", containerElement)
1
2
3
4
5
2
3
4
5
Item Rendering
javascript
const customList = {
...list,
renderItem(item, index) {
return html`
<div class="item" @click=${() => console.log(item)}>
<h3>${item.name}</h3>
<p>${item.description}</p>
</div>
`
},
}
1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
Performance Tips
- Use
renderItemfor consistent item height - Set
itemHeightexplicitly if possible - Increase
bufferSizeif scrolling feels jittery - Use repeat() directive if items can reorder
Inglorious Web