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>
  );
}

Usage with useFilteredItems

When using Base UI's useFilteredItems() hook, filtered items come from inside the Root component. This requires a child component pattern with virtualizerRef + useHighlightHandler:


import {
  AutocompleteRoot,
  AutocompleteVirtualizedList,
  useAutocompleteFilteredItems,
} from "@/components/ui/cubby-ui/autocomplete";
import {
  useListVirtualizer,
  useHighlightHandler,
  type ListVirtualizerInstance,
} from "@/hooks/cubby-ui/use-list-virtualizer";
 
function MyAutocomplete({ items }) {
  const virtualizerRef = React.useRef<ListVirtualizerInstance>(null);
  const onItemHighlighted = useHighlightHandler(virtualizerRef);
 
  return (
    <AutocompleteRoot
      items={items}
      virtualized
      itemToStringValue={getLabel}
      onItemHighlighted={onItemHighlighted}
    >
      {/* Input, positioner, etc. */}
      <VirtualizedContent items={items} virtualizerRef={virtualizerRef} />
    </AutocompleteRoot>
  );
}
 
function VirtualizedContent({ items, virtualizerRef }) {
  const filteredItems = useAutocompleteFilteredItems();
  const { scrollRef, measureRef, totalSize, virtualItems, getItem, getItemStyle, getItemProps } =
    useListVirtualizer({ items, filteredItems, virtualizerRef });
 
  return (
    <AutocompleteVirtualizedList scrollRef={scrollRef} totalSize={totalSize}>
      {virtualItems.map((vi) => { /* ... */ })}
    </AutocompleteVirtualizedList>
  );
}

This eliminates manual query state, useDeferredValue, useFilter(), and useMemo filtering. The Root handles filtering internally, and useFilteredItems() provides the result to the virtualizer.

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

useHighlightHandler


function useHighlightHandler(
  virtualizerRef: React.RefObject<ListVirtualizerInstance | null>,
): (item: unknown, details: { reason: string; index: number }) => void;

Returns a stable onItemHighlighted callback that scrolls the virtualizer to the highlighted item on keyboard navigation. Use this on the Root component when the virtualizer lives in a child component.

ListVirtualizerInstance


type ListVirtualizerInstance = ReturnType<typeof useVirtualizer>;

Type alias for the virtualizer instance. Use to type the virtualizerRef.

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
Combobox - For virtualized combobox lists