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()
+})