Skip to content
Nana UI

Data Display & Media

Virtual List

A long list — a ledger of thousands of payments, every meter reading in a block — that stays quick because only the rows in view, and a few either side, are ever in the page. Set items to the data and renderItem to turn one entry into its row; every row is item-height pixels tall.

View .md Download

The rows carry their place in the whole list, so assistive tech announces “12 of 4,000” rather than counting only what happens to be rendered. The list scrolls by keyboard once focused.

Load 5,000 payments No payments loaded yet.
  • #1 · Unit 1 KES 12,000
  • #2 · Unit 2 KES 12,037
  • #3 · Unit 3 KES 12,074
  • #4 · Unit 4 KES 12,111
npm install @nana-tec/ui-components

Or copy the source in and own it:

npx @nana-tec/ui add virtual-list --framework web-components
npx @nana-tec/ui add virtual-list --framework svelte

Lands in src/lib/components/ui/virtual-list/ as NanaVirtualList.svelte, styled with Tailwind classes that resolve to the design tokens. Requires Tailwind v4.

Import the autoloader once, in your app's entry point. Every <nana-*> tag then works anywhere, and each component downloads only the first time a page uses it:

import "@nana-tec/ui-components/autoloader";
import "@nana-tec/ui-components/theme";

The second line gives every component the Nana look and the design tokens behind it. Leave it out to style the components entirely yourself.

Import a component directly when it must be ready at once: on screen at first paint, or when you call its methods straight away. The two mix freely:

import "@nana-tec/ui-components/virtual-list";

Copied in with npx @nana-tec/ui add virtual-list? Import your project's own @/lib/nana-ui/autoloader.js once instead; the CLI keeps it up to date.

The example below sets the list’s properties straight away, so it imports the list directly.

<script lang="ts">
import { NanaVirtualList } from '$lib/components/ui/virtual-list';
let list: NanaVirtualList<Payment>;
</script>
<NanaVirtualList bind:this={list} items={payments} itemHeight={44} label="Payments">
{#snippet item(payment, index)}{payment.tenant}{/snippet}
{#snippet empty()}No payments yet{/snippet}
</NanaVirtualList>
<button onclick={() => list.scrollToIndex(0)}>Back to the top</button>

Only the rows in view, and overscan either side, are in the page, so thousands stay quick. Every row is itemHeight pixels tall. Rows carry their place in the whole list, so assistive tech announces “12 of 5,000”. onRangeChange reports which rows are rendered.

items and renderItem are properties, not attributes — set them from script or bind them in your framework:

import "@nana-tec/ui-components/virtual-list";
import { html } from "lit";
const ledger = document.querySelector("nana-virtual-list");
ledger.items = payments;
ledger.renderItem = (payment, index) => html`
<span>${payment.date}</span>
<span>${payment.tenant}</span>
<span>KES ${payment.amount.toLocaleString("en-KE")}</span>
`;

renderItem can return a Lit template, a DOM node or a string. Without it each entry is shown as text.

Every row is item-height pixels tall — the list works out what is in view from that alone, so a row that wraps onto a second line will be clipped. Give the list a height with --nana-virtual-list-height, and call scrollToIndex(i) to jump to a row.

Reach for it when a list runs to thousands of rows. Below a few hundred, a plain list or a table is simpler and lets the browser’s find-in-page see every row.

ledger.addEventListener("nana-range-change", (e) => {
const { start, end } = e.detail;
if (end > ledger.items.length - 50) loadMore();
});

Properties

PropertyAttributeTypeDefaultDescription
itemHeightitem-heightnumber40The height of every row, in px
items—readonly T[][]The full data set
labellabelstring''Accessible name for the list
overscanoverscannumber4Rows rendered beyond each edge of the view, so a fast scroll doesn't show blanks
renderItem—VirtualListRenderItem<T> | undefined—Turns one entry into its row; without it the entry is shown as text

Methods

MethodDescription
scrollToIndex(index: number): voidScroll so the row at index is at the top of the view

Events

EventDescription
nana-range-changeThe rendered rows changed (detail.start, detail.end, end exclusive)

Slots

SlotDescription
emptyShown when there are no items

CSS parts

PartDescription
::part(viewport)The scrolling area
::part(list)The rows currently rendered
::part(item)One row
::part(empty)The empty
::part(spacer)The spacer

CSS custom properties

PropertyDescription
--nana-virtual-list-heightHeight of the scrolling area

NanaVirtualList

PropTypeDefault
itemsrequiredreadonly T[]
itemSnippet<[T, number]>
emptySnippet
itemHeightnumber40
overscannumber4
labelstring
onRangeChange(range: { start: number; end: number }) => void

Also accepts Omit<HTMLAttributes<HTMLDivElement>, 'class'>.