useListVirtualizer

Installation

npx shadcn@latest add @cubby-ui/use-list-virtualizer

useListVirtualizer provides virtualization for large lists using TanStack Virtual. It handles scroll positioning, item measurement, and keyboard navigation, making it easy to render thousands of items without performance issues.

When to use:

Lists with 100+ items
Command menus, autocompletes, or selects with large datasets
Any scrollable list where DOM node count impacts performance

Usage


import { useListVirtualizer } from "@/hooks/cubby-ui/use-list-virtualizer";
 
const {
  rootProps,       // Spread on root component
  scrollRef,       // Attach to scroll container
  measureRef,      // Attach to each item for dynamic heights
  totalSize,       // Total height for virtual container
  virtualItems,    // Array to map over
  getItem,         // Get data for virtual item
  getItemStyle,    // Get positioning styles
  getItemProps,    // Get aria attributes
} = useListVirtualizer({
  items,           // All items (for aria-setsize)
  filteredItems,   // Items to display
  estimateSize: 40, // Item height in px
});

Example with Command


import { useListVirtualizer } from "@/hooks/cubby-ui/use-list-virtualizer";
import {
  Command,
  CommandVirtualizedList,
  CommandItem,
} from "@/lib/cubby-ui/command";
 
// Helper to extract searchable text from items
const getItemLabel = (item: Item | null) => item?.label ?? "";
 
function VirtualizedCommand({ items, filteredItems }) {
  const {
    rootProps,
    scrollRef,
    measureRef,
    totalSize,
    virtualItems,
    getItem,
    getItemStyle,
    getItemProps,
  } = useListVirtualizer({
    items,
    filteredItems,
    estimateSize: 40,
  });
 
  return (
    <Command {...rootProps} filter={null} itemToStringValue={getItemLabel}>
      <CommandVirtualizedList scrollRef={scrollRef} totalSize={totalSize} nativeScroll>
        {virtualItems.map((virtualItem) => {
          const item = getItem(virtualItem);
          return (
            <CommandItem
              key={virtualItem.key}
              ref={measureRef}
              value={item}
              style={getItemStyle(virtualItem)}
              {...getItemProps(virtualItem)}
            >
              {item.label}
            </CommandItem>
          );
        })}
      </CommandVirtualizedList>
    </Command>
  );
}

Performance Tips

For optimal scroll performance with large lists:

Use useDeferredValue for search queries - Prevents filtering from blocking scroll rendering. Use the resolved pattern to avoid stale results when clearing:


const deferredQuery = React.useDeferredValue(query);
// Use immediate value when empty to avoid stale results
const resolvedQuery =
  query === "" || deferredQuery === "" ? query : deferredQuery;
 
const filteredItems = React.useMemo(
  () => items.filter((item) => contains(item, resolvedQuery, getLabel)),
  [contains, resolvedQuery],
);

Use nativeScroll on CommandVirtualizedList - Avoids custom scroll container overhead for smoother fast scrolling.

API Reference

Options

Prop

Type

Default

Return Value

Property	Type	Description
`rootProps`	`object`	Spread on root component. Includes `virtualized`, `items`, `filteredItems`, `onItemHighlighted`
`scrollRef`	`(el: HTMLDivElement \| null) => void`	Ref callback for the scroll container
`measureRef`	`(el: HTMLDivElement \| null) => void`	Ref callback for each item (enables dynamic heights)
`totalSize`	`number`	Total height of all virtual items in pixels
`virtualItems`	`VirtualItem[]`	Array of virtual items to render
`getItem`	`(virtualItem) => T \| undefined`	Get the data item for a virtual item
`getItemStyle`	`(virtualItem) => CSSProperties`	Get positioning styles for a virtual item
`getItemProps`	`(virtualItem) => object`	Get aria attributes (`aria-setsize`, `aria-posinset`, `data-index`, `index`)

Used By

Command - For virtualized command menus
Autocomplete - For virtualized autocomplete lists