diff --git a/docs/api/virtualizer.md b/docs/api/virtualizer.md index a5715fbc1..dba8cc240 100644 --- a/docs/api/virtualizer.md +++ b/docs/api/virtualizer.md @@ -226,6 +226,48 @@ gap?: number This option allows you to set the spacing between items in the virtualized list. It's particularly useful for maintaining a consistent visual separation between items without having to manually adjust each item's margin or padding. The value is specified in pixels. +### `indexAttribute` + +```tsx +indexAttribute?: string +``` + +**Default:** `'data-index'` + +The name of the DOM attribute the virtualizer reads to find out which item a measured element belongs to. It is read by `measureElement` and by the `ResizeObserver` that keeps measurements up to date, so every element you measure must carry it, set to the item's index. + +The default is enough for a single virtualizer. Change it when **two virtualizers measure the same element**, as in a grid with both a row and a column virtualizer: a cell can't carry two different indexes in one `data-index` attribute, so give each virtualizer its own attribute: + +```tsx +const rowVirtualizer = useVirtualizer({ + count: rows.length, + getScrollElement: () => parentRef.current, + estimateSize: () => 35, + indexAttribute: 'data-row-index', +}) + +const columnVirtualizer = useVirtualizer({ + horizontal: true, + count: columns.length, + getScrollElement: () => parentRef.current, + estimateSize: () => 100, + indexAttribute: 'data-column-index', +}) + +// ... + +
{ + rowVirtualizer.measureElement(node) + columnVirtualizer.measureElement(node) + }} +/> +``` + +If the attribute is missing on a measured element, the virtualizer logs a warning (`Missing attribute name '={index}' on measured element.`) and skips the measurement. + ### `lanes` ```tsx diff --git a/packages/virtual-core/tests/measurement.test.ts b/packages/virtual-core/tests/measurement.test.ts index a53db446c..af6981456 100644 --- a/packages/virtual-core/tests/measurement.test.ts +++ b/packages/virtual-core/tests/measurement.test.ts @@ -1225,3 +1225,84 @@ test('refreshes horizontal end alignment when a scrollbar toggles', () => { } virtualizer._didMount()() }) + +// ─── indexAttribute ────────────────────────────────────────────────────────── + +test('indexAttribute lets a row and a column virtualizer measure the same cell', () => { + const createVirtualizer = (horizontal: boolean, indexAttribute?: string) => { + const virtualizer = new Virtualizer({ + count: 10, + horizontal, + indexAttribute, + estimateSize: () => 50, + getScrollElement: () => null, + scrollToFn: vi.fn(), + observeElementRect: (_instance, cb) => { + cb({ width: 400, height: 400 }) + return () => {} + }, + observeElementOffset: (_instance, cb) => { + cb(0, false) + return () => {} + }, + }) + virtualizer._willUpdate() + // Seed the measurements, as a render does before refs call measureElement. + virtualizer['getMeasurements']() + return virtualizer + } + + const rows = createVirtualizer(false, 'data-row-index') + const columns = createVirtualizer(true, 'data-column-index') + + // A grid cell at row 2, column 5. A single `data-index` could not carry both. + const attributes: Record = { + 'data-row-index': '2', + 'data-column-index': '5', + } + const cell = { + getAttribute: (name: string) => attributes[name] ?? null, + offsetHeight: 80, + offsetWidth: 120, + isConnected: true, + } as unknown as HTMLElement + + rows.measureElement(cell) + columns.measureElement(cell) + + expect(rows.elementsCache.get(2)).toBe(cell) + expect(columns.elementsCache.get(5)).toBe(cell) + const rowMeasurements = rows['getMeasurements']() + const columnMeasurements = columns['getMeasurements']() + expect(rowMeasurements[2]!.size).toBe(80) + expect(columnMeasurements[5]!.size).toBe(120) + // Neither virtualizer touched the other's index. + expect(rowMeasurements[5]!.size).toBe(50) + expect(columnMeasurements[2]!.size).toBe(50) +}) + +test('indexAttribute defaults to data-index and warns when the attribute is missing', () => { + const virtualizer = new Virtualizer({ + count: 3, + estimateSize: () => 50, + getScrollElement: () => null, + scrollToFn: vi.fn(), + observeElementRect: vi.fn(), + observeElementOffset: vi.fn(), + }) + const node = { + getAttribute: (name: string) => (name === 'data-index' ? '1' : null), + } as unknown as HTMLElement + expect(virtualizer.indexFromElement(node)).toBe(1) + + const custom = new Virtualizer({ + ...virtualizer.options, + indexAttribute: 'data-row-index', + }) + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}) + expect(custom.indexFromElement(node)).toBe(-1) + expect(warn).toHaveBeenCalledWith( + "Missing attribute name 'data-row-index={index}' on measured element.", + ) + warn.mockRestore() +})