Virtualizer-scroll-to-element

[NarekPoghosyan]

🙋 Documentation Request

Issue Description

When using Virtualizer from the react-aria-components package together with ListBox, I need to scroll the list to a specific item (scroll-to-item). However, due to the current virtualization implementation, this is problematic because:

Virtualizer wraps the list items in a div that is inaccessible from outside.

The parent ListBox has a fixed height, but the inner div (where the items actually live) becomes much taller and does not respect the parent’s boundaries.

Hence, there’s no direct way to call scrollTo, scrollIntoView, etc. on the desired element within the Virtualizer. Below is a shortened version of my code.

Код

import cn from 'clsx'
import { useTranslations } from 'next-intl'
import { useCallback, useEffect, useMemo, useRef } from 'react'
import { Button, ListBox, ListBoxItem, ListLayout, Virtualizer } from 'react-aria-components'
import { useForm } from 'react-final-form'
import { MdCheck as IconCheck } from 'react-icons/md'

import { ListBoxPropTypes } from '@/components/_fields/FieldSelectNew/_types'
import { styles } from '@/components/_fields/FieldSelectNew/stylesFieldSelectNew'
import { compareWithWrongKeyboardLayout } from '@/utils/compareWithWrongKeyboardLayout/compareWithWrongKeyboardLayout'
import { useCheckViewport } from '@/utils/useCheckViewport/useCheckViewport'

export function ListBoxSelect({
  handleChange,
  inputValue,
  isInputChange,
  isOpen,
  name,
  optionId,
  options,
  rounded,
  updateSelectState
}: ListBoxPropTypes): JSX.Element {
  const { isMobile } = useCheckViewport()
  const t = useTranslations()
  const form = useForm()
  const itemRefs = useRef<Record<string, HTMLButtonElement | null>>({})

  const getItemRef = (id: string | number) => (node: HTMLButtonElement | null) => {
    if (!node) return
    itemRefs.current[id.toString()] = node
  }

  const matchedComposers = useMemo(() => {
    if (isInputChange) {
      return options?.filter((composer) =>
        compareWithWrongKeyboardLayout({
          compareText: composer?.name,
          fromFirstIndex: true,
          ignoreNonAlphanumeric: false,
          search: inputValue
        })
      )
    }
    return []
  }, [inputValue, isInputChange, options])

  const data = isInputChange ? matchedComposers : options

  const onSelectionChange = useCallback((optionValue: string, optionName: string) => {
    handleChange?.(optionValue)
    form.batch(() => {
      form.change(name, optionValue)
    })
    updateSelectState('optionId', optionValue)
    updateSelectState('inputValue', optionName)
    updateSelectState('isOpen', false)
  }, [form, name, handleChange, updateSelectState])

  useEffect(() => {
    if (isOpen && optionId) {
      setTimeout(() => {
        const refEl = itemRefs.current[optionId.toString()]
        if (refEl) {
          // Attempt to scroll to the required element
          refEl.scrollIntoView({
            behavior: 'instant',
            block: 'center'
          })
        }
      }, 0)
    }
  }, [isOpen, optionId])

  return (
    <Virtualizer
      layout={ListLayout}
      layoutOptions={{ rowHeight: isMobile ? 46 : 40 }}
    >
      <ListBox
        aria-label='Virtualized ListBox'
        className={cn(
          styles.rounded[rounded],
          'max-h-280 block w-full overflow-auto p-0 outline-none'
        )}
        items={data}
        renderEmptyState={() => (
          <span className={cn(
            'h-46 text-16 flex w-full max-w-full items-center px-16 py-2 text-left font-medium',
            'sm:px-20'
          )}>
            {t('common.select.emptyText')}
          </span>
        )}
      >
        {(item) => (
          <ListBoxItem
            className={'group flex h-full w-full select-none items-center rounded outline-none'}
            data-id={item?.id}
            key={`${item?.id}key${item?.name}`}
          >
            {({ isSelected }) => (
              <Button
                className={cn(
                  'text-16 transition-bg relative flex h-full w-full max-w-full cursor-pointer items-center px-16 text-left font-medium sm:px-20',
                  item?.id?.toString() === optionId?.toString()
                    ? 'bg-purple-light text-white'
                    : 'hover:bg-purple-lightest text-black'
                )}
                onPress={() => onSelectionChange(item?.id, item?.name)}
                ref={getItemRef(item.id)}
              >
                <span className={'group-selected:font-medium flex flex-1 items-center gap-3 truncate font-normal'}>
                  <span className={'truncate'}>
                    {item?.name}
                  </span>
                </span>
                {isSelected && (
                  <span className={'text-20 flex items-center text-sky-600 group-focus:text-white'}>
                    <IconCheck className={'h-24 w-24'} />
                  </span>
                )}
              </Button>
            )}
          </ListBoxItem>
        )}
      </ListBox>
    </Virtualizer>
  )
}

Current Behavior
The list is virtualized.

The scrollIntoView() method is called, but it does not work as expected: the element does not scroll into the correct position within the list, likely because the virtualized container is “taller” and not strictly bound to the parent’s boundaries.

Expected Behavior
Ability to control scrolling within the virtualized list: for example, “scroll” to the needed item by optionId or call a method/callback that does it inside the Virtualizer.

Optionally, extend or add a built-in API that allows passing scrollToItem() or a similar method without having to go through the inner div.

Question
Will Virtualizer (or the relevant part of the library) include the ability to scroll to a specific item (scroll-to-item) in the near future? If so, is there any timeframe or example of how to achieve this with the library?

I would greatly appreciate any advice or ready-made solution on how to implement “scroll to item” functionality using Virtualizer.

Additional Information
React: 19.0.0
react-aria-components: 1.7.1
OS: MacOS

Browsers: Chrome

P.S. Thank you in advance for any help or guidance on how to implement this feature!

🧢 Your Company/Team

No response

[nwidynski]

@NarekPoghosyan Hey there, do you mind providing a sandbox so I can take a closer look?

Since the Virtualizer specifies a fixed row height you should be able to use listBoxRef.scrollBy(rowHeight * index).

[henkkasoft]

@NarekPoghosyan Hey there, do you mind providing a sandbox so I can take a closer look?

Since the Virtualizer specifies a fixed row height you should be able to use listBoxRef.scrollBy(rowHeight * index).

I have a similar problem with virtualized Table and wondering how can I scroll to specific row if that row is on the bottom of the table and because of virtualizer it is correctly not even rendered. I think it would be really helpful to be able to tell to which item to scroll to?

Tried to implement this by adding ref to ResizableTableContainer or Table and scrolling in useEffect but it didn't work out.

  useEffect(() => {
    if (indexToScroll !== -1 && scrollRef.current) {
      scrollRef.current.scrollTop = 42 * indexToScroll;
    }
  }, [indexToScroll, rows]);

I think the problem is that ResizableTableContainer can be scrolled but it has only the height of the really rendered rows not virtualized ones at the bottom.

It would be really great to be able to tell virtualizer where to scroll or what is the first item I want the list to start and I could start scrolling up or down from there. Or is there something like that existing?

[nwidynski]

@henkkasoft Just to clarify, is your code scrolling to the wrong offset or is the scroll not applied at all? If its the later, can you try to apply the scrollTop in the next frame via requestAnimationFrame()?

If you are working with varying row heights, you can try to retrieve the layoutDelegate from the collection renderer context, then use its getItemRect() function to query for the items layout position. You should then be able to scrollTo({top: rect.y}). Remember to subtract gaps and possibly padding from the scroll position if desired 👍

Disclaimer: This may still scroll to the wrong position if the item target has not yet ever been rendered in view, therefore its position is only estimated by the estimatedRowHeight option of the layout you are using.