@tanstack/lit-virtual

Efficiently virtualize only the visible DOM nodes within massive scrollable elements using Lit, while maintaining complete control over markup and styles.

VirtualizerController

@tanstack/lit-virtual utilizes Reactive Controllers to create the virtualizer and integrate it with the element lifecycle:

1import { LitElement } from 'lit'
2import { VirtualizerController } from '@tanstack/lit-virtual'
3import { Ref, createRef } from 'lit/directives/ref.js'
4
5class MyVirtualElement extends LitElement {
6  private virtualizerController: VirtualizerController<HTMLDivElement, Element>
7  private scrollElementRef: Ref<HTMLDivElement> = createRef()
8
9  constructor() {
10    super()
11    this.virtualizerController = new VirtualizerController(this, {
12      getScrollElement: () => this.scrollElementRef.value,
13      count: 10000,
14      estimateSize: () => 35,
15      overscan: 5,
16    })
17  }
18
19  render() {
20    const virtualizer = this.virtualizerController.getVirtualizer()
21    const virtualItems = virtualizer.getVirtualItems()
22
23    return html`
24      <div class="list scroll-container" ${ref(this.scrollElementRef)}>
25        ${virtualItems.map(
26          (item) => html`<div class="item">${item.index}</div>`,
27        )}
28      </div>
29    `
30  }
31}

Note that a Ref is attached to the scrolling container to allow the virtualizer to interact with it.

WindowVirtualizerController

You can also create a virtualizer controller that attaches to the Window:

1import { WindowVirtualizerController } from '@tanstack/lit-virtual'
2
3class MyWindowVirtualElement extends LitElement {
4  private windowVirtualizerController: WindowVirtualizerController
5
6  constructor() {
7    super()
8    this.windowVirtualizerController = new WindowVirtualizerController(this, {
9      count: this.data.length,
10      estimateSize: () => 350,
11      overscan: 5,
12    })
13  }
14
15  // Implement render and other lifecycle methods as needed
16}

For more examples and detailed usage, visit the official documentation.