useListVirtualizer

1import * as React from "react";
2import { useVirtualizer, type VirtualItem } from "@tanstack/react-virtual";
3 
4/**
5 * The virtualizer instance type. Use to type a ref that receives
6 * the virtualizer via the `virtualizerRef` option.
7 */
8export type ListVirtualizerInstance = ReturnType<
9  typeof useVirtualizer<HTMLDivElement, Element>
10>;
11 
12/**
13 * Returns a stable `onItemHighlighted` handler that scrolls the virtualizer
14 * to the highlighted item on keyboard navigation.
15 *
16 * Use this on the Root component when the virtualizer lives in a child
17 * component (e.g. when using `useFilteredItems`).
18 */
19export function useHighlightHandler(
20  virtualizerRef: React.RefObject<ListVirtualizerInstance | null>,
21) {
22  return React.useCallback(
23    (
24      item: unknown,
25      {
26        reason,
27        index,
28      }: { reason: "none" | "keyboard" | "pointer"; index: number },
29    ) => {
30      const virtualizer = virtualizerRef.current;
31      if (!item || !virtualizer) return;
32 
33      const isStart = index === 0;
34      const isEnd = index === virtualizer.options.count - 1;
35 
36      const shouldScroll =
37        reason === "none" || (reason === "keyboard" && (isStart || isEnd));
38 
39      if (shouldScroll) {
40        queueMicrotask(() => {
41          virtualizer.scrollToIndex(index, {
42            align: isEnd ? "start" : "end",
43          });
44        });
45      }
46    },
47    // virtualizerRef is a stable ref object
48    // eslint-disable-next-line react-hooks/exhaustive-deps
49    [],
50  );
51}
52 
53export interface UseListVirtualizerOptions<T> {
54  /**
55   * Whether virtualization is enabled.
56   * Typically tied to whether the list container is open/visible.
57   * @default true
58   */
59  enabled?: boolean;
60 
61  /**
62   * All items in the list (unfiltered).
63   * Used by Base UI Autocomplete for proper aria-setsize.
64   */
65  items: T[];
66 
67  /**
68   * The filtered items to display.
69   * Can be the same as `items` if no filtering is applied (e.g., server-side filtering).
70   */
71  filteredItems: T[];
72 
73  /**
74   * Estimated height of each item in pixels, or a function that returns
75   * the estimate for each item. Used for initial layout before measurement.
76   * @default 40
77   */
78  estimateSize?: number | ((index: number, item: T) => number);
79 
80  /**
81   * Number of items to render outside the visible area.
82   * Higher values = smoother scrolling, more memory.
83   * @default 20
84   */
85  overscan?: number;
86 
87  /**
88   * Padding at the start of the list in pixels.
89   * Should match the list container's padding.
90// … truncated