Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions docs/api/virtualizer.md
Original file line number Diff line number Diff line change
Expand Up @@ -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',
})

// ...

<div
data-row-index={virtualRow.index}
data-column-index={virtualColumn.index}
ref={(node) => {
rowVirtualizer.measureElement(node)
columnVirtualizer.measureElement(node)
}}
/>
```

If the attribute is missing on a measured element, the virtualizer logs a warning (`Missing attribute name '<indexAttribute>={index}' on measured element.`) and skips the measurement.

### `lanes`

```tsx
Expand Down
81 changes: 81 additions & 0 deletions packages/virtual-core/tests/measurement.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, string> = {
'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()
})