Function: createVirtualizer()

createVirtualizer<Item>(initialOptions): VirtualizerHandle<Item>

Creates an accessible vertical list/grid virtualizer with deterministic SSR output. The handle owns its viewport through ref and remains inert when browser observers are unavailable.

Type Parameters

Item

Item

Parameters

initialOptions

VirtualizerOptions<Item>

Returns

VirtualizerHandle<Item>

Example

Render a bounded product inventory with stable keys, semantic grid metadata, dynamic measurement, deterministic server content, and owned cleanup:

import {
  createVirtualizer,
  html,
  type VirtualizerHandle,
  type VirtualizerLayout,
  type VirtualizerOptions,
  type VirtualizerRange,
} from '@gluonjs/core';

interface Product { readonly id: string; readonly name: string }
const inventory: readonly Product[] = Array.from({ length: 100 }, (_, index) => ({
  id: `sku-${index}` ,
  name: `Product ${index + 1}` ,
}));
const layout: VirtualizerLayout = 'grid';
const options: VirtualizerOptions<Product> = {
  items: inventory,
  key: (product) => product.id,
  renderItem: (product) => html`<a href=${`/products/${product.id}`}>${product.name}</a>`,
  estimateSize: 72,
  layout,
  columns: 2,
  overscan: 2,
  ssrCount: 8,
  ariaLabel: 'Product inventory',
};
const products: VirtualizerHandle<Product> = createVirtualizer(options);
const view = products.view();
const range: VirtualizerRange = products.range.value;
products.scrollToIndex(40, { behavior: 'smooth', focus: true });
console.log(view, range);