Clusterize-Lazy

Vanilla-JS virtual list with lazy loading and initial skeletons.

Clusterize-Lazy lets you render millions of rows in a scrollable container while downloading data only for what the user can actually see. Its goal is an easy, framework-agnostic API that just works in any modern browser - no build step required.

Small footprint, great DX - powered by @tanstack/virtual-core

Features

• Single dependency - relies on the rock-solid engine
  @tanstack/virtual-core (thanks Tanner & the TanStack team!)
• Dynamic row height - actual DOM sizes are measured automatically
• Lazy loading + skeletons - smooth UX even on shaky connections
• Typed from the ground up - shipped .d.ts works in ESM browsers and legacy browsers (with polyfills)
• Batteries included - debug logging, auto cache eviction, progress callback

Live demo

Test it instantly (no transpiler):
https://joobypm.github.io/clusterize-lazy/examples/quotes.html

Source lives in docs/examples/

Installation

pnpm / npm / Yarn

pnpm add clusterize-lazy

import Clusterize from 'clusterize-lazy';
const cluster = Clusterize({...});

<script> tag (UMD)

<script src="https://unpkg.com/clusterize-lazy/dist/index.iife.js"></script>
<script>
  const cluster = Clusterize.default({...});
</script>

30-second example

<div id="scroll" style="height: 320px; overflow: auto">
	<div id="content"></div>
</div>

<script type="module">
	import Clusterize from '/dist/index.esm.js';

	function fetchRows(offset, size = 40) {
		return fetch(`/api/items?skip=${offset}&limit=${size}`).then((r) => r.json());
	}

	const cluster = Clusterize({
		rowHeight: 32,
		scrollElem: document.getElementById('scroll'),
		contentElem: document.getElementById('content'),

		fetchOnInit: async () => {
			const rows = await fetchRows(0);
			return { totalRows: 50_000, rows };
		},
		fetchOnScroll: fetchRows,
		renderSkeletonRow: (h, i) => `<div class="skeleton" style="height:${h}px"></div>`,
		renderRaw: (i, row) => `<div>${i + 1}. ${row.title}</div>`,
	});
</script>

Mutation example

// Enable mutations with buildIndex
const cluster = Clusterize({
	rowHeight: 40,
	buildIndex: true,        // Enable ID-based operations
	primaryKey: 'id',        // Use 'id' field as primary key
	scrollElem: document.getElementById('scroll'),
	contentElem: document.getElementById('content'),
	
	fetchOnInit: () => Promise.resolve([
		{ id: 1, name: 'Alice', status: 'active' },
		{ id: 2, name: 'Bob', status: 'inactive' },
		{ id: 3, name: 'Charlie', status: 'active' }
	]),
	fetchOnScroll: () => Promise.resolve([]),
	renderSkeletonRow: (h) => `<div style="height:${h}px">Loading...</div>`,
	renderRaw: (i, row) => `<div>${row.name} (${row.status})</div>`
});

// Add new rows
cluster.insert([{ id: 4, name: 'David', status: 'active' }], 1);

// Update existing row by ID
cluster.update([{ id: 2, data: { id: 2, name: 'Bob', status: 'active' } }]);

// Remove rows by ID
cluster.remove([1, 3]);

Quick reference

Option / method	Type / default	Purpose
required
rowHeight	number	Fixed row estimate (px)
fetchOnInit()	() ⇒ Promise<Row[] | { totalRows, rows }>	First data batch or rows + total count
fetchOnScroll(offset)	(number) ⇒ Promise<Row[]>	Fetches when a gap becomes visible
renderSkeletonRow(height,index)	(number,number) ⇒ string	Placeholder HTML
optional
renderRaw(index,data)	(number,Row) ⇒ string · undefined	Row renderer for object data
buffer	5	Rows rendered above/under viewport
prefetchRows	buffer	Rows fetched ahead of viewport
debounceMs	120	Debounce between scroll & fetch
cacheTTL	300 000	Milliseconds before a cached row is stale
autoEvict	false	Drop stale rows automatically
showInitSkeletons	true	Paint skeletons immediately before first fetch
debug	false	Console debug output
scrollingProgress(cb)	(firstVisible:number) ⇒ void	Fires on every render
buildIndex	false	Build ID-to-index map for mutations
primaryKey	'id'	Property name for primary key
methods
refresh()	void	Force re-render
scrollToRow(idx, smooth?)	void ( true = smooth)	Programmatic scroll
getLoadedCount()	number	How many rows are cached
destroy()	void	Tear down listeners & cache
insert(rows, at?)	void	Insert rows at position (default: 0)
update(patches)	void	Update rows by ID or index
remove(keys)	void	Remove rows by ID or index
_dump()	{ cache, index }	Debug helper for internal state

See docs/API.md for the full contract.

Contributing

git clone https://github.com/JoobyPM/clusterize-lazy.git
pnpm i
pnpm test      # vitest + jsdom
pnpm build     # tsup + esbuild

Formatting & linting are handled by Deno (deno fmt, deno lint). Please follow Conventional Commits; releases are automated.

Acknowledgements

Huge shout-out to [@tanstack/virtual-core] - Clusterize-Lazy is basically a thin, opinionated shell around this fantastic engine. If you need a React / Vue / Solid binding or more power, use the TanStack package directly and consider sponsoring the project.

License

MIT © 2025 JoobyPM