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.
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.
Preview
Section titled “Preview”<nana-button
variant="secondary"
onclick="
const list = document.getElementById('ledger-preview');
list.items = Array.from(
{ length: 5000 },
(_, i) =>
'Payment ' +
(i + 1) +
' · Unit ' +
(1 + (i % 12)) +
'ABCD'[i % 4] +
' · KES ' +
(18000 + ((i * 3700) % 40000)).toLocaleString('en-KE'),
);
"
>
Load 5,000 payments
</nana-button>
<nana-virtual-list
id="ledger-preview"
item-height="40"
label="Payments"
style="--nana-virtual-list-height: 18rem"
>
<span slot="empty">No payments loaded yet.</span>
</nana-virtual-list> - #1 · Unit 1 KES 12,000
- #2 · Unit 2 KES 12,037
- #3 · Unit 3 KES 12,074
- #4 · Unit 4 KES 12,111
<script lang="ts">
import { NanaVirtualList } from '$lib/components/ui/virtual-list';
const payments = Array.from({ length: 5000 }, (_, index) => ({
id: index + 1,
unit: `Unit ${(index % 40) + 1}`,
amount: 12000 + ((index * 37) % 9000),
}));
</script>
<NanaVirtualList items={payments} itemHeight={44} label="Payments" class="h-72 w-full max-w-md">
{#snippet item(payment)}
<span class="flex w-full justify-between">
<span>#{payment.id} · {payment.unit}</span>
<span class="tabular-nums">KES {payment.amount.toLocaleString()}</span>
</span>
{/snippet}
</NanaVirtualList> Installation
Section titled “Installation”npm install @nana-tec/ui-componentsOr copy the source in and own it:
npx @nana-tec/ui add virtual-list --framework web-componentsnpx @nana-tec/ui add virtual-list --framework svelteLands in src/lib/components/ui/virtual-list/ as NanaVirtualList.svelte, styled with Tailwind
classes that resolve to the design tokens. Requires Tailwind v4.
Import
Section titled “Import”
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
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
itemHeight | item-height | number | 40 | The height of every row, in px |
items | — | readonly T[] | [] | The full data set |
label | label | string | '' | Accessible name for the list |
overscan | overscan | number | 4 | Rows 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
| Method | Description |
|---|---|
scrollToIndex(index: number): void | Scroll so the row at index is at the top of the view |
Events
| Event | Description |
|---|---|
nana-range-change | The rendered rows changed (detail.start, detail.end, end exclusive) |
Slots
| Slot | Description |
|---|---|
empty | Shown when there are no items |
CSS parts
| Part | Description |
|---|---|
::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
| Property | Description |
|---|---|
--nana-virtual-list-height | Height of the scrolling area |
NanaVirtualList
| Prop | Type | Default |
|---|---|---|
itemsrequired | readonly T[] | |
item | Snippet<[T, number]> | |
empty | Snippet | |
itemHeight | number | 40 |
overscan | number | 4 |
label | string | |
onRangeChange | (range: { start: number; end: number }) => void |
Also accepts Omit<HTMLAttributes<HTMLDivElement>, 'class'>.