Best way to preserve scroll position when new items added to beginning of the list

[cbelden]

I'm using the virtualizer to render a list of dynamically sized items, and I was hoping to get some advice on how to preserve the currently visible items when a new item is added to the beginning of the list (particularly when that item is not visible/offscreen).

Steps to repro

1. Scroll deeply into a virtualized list
2. Add a new item to the beginning of the list

Expected

Existing scroll position remains the same (from the user's perspective at least)

Actual

Content shifts down

Ideas

1. detect when new items are added, and try to adjust the scroll position accordingly. this seems difficult to do outside of the library, but happy to hear ideas!
2. build this into the library, seems like this might be a generally useful feature, particularly for lists that can have items added to the beginning while the user is viewing the list.

Looking for any feedback/tips, maybe this is already supported! Thanks

[GarrisonBates]

I've just been working on this for the past week. I've found this thread to be very useful when working on the same problem:
#195

My use case is a messaging interface. Code's a little messy right now but I'll share in case it helps:

import { useMembers } from '@/api/queries/members/useMembers'
import { useMessagesInfinite } from '@/api/queries/messages/useMessagesInfinite'
import { InfiniteScrollSentinel } from '@/components/InfiniteScrollSentinel'
import Loading from '@/components/Loading'
import { Message } from '@/pages/Chat/Message'
import { NewMessageOverlay } from '@/pages/Chat/NewMessagesOverlay'
import { useUserId } from '@/state/hooks'
import { useVirtualizer } from '@tanstack/react-virtual'
import {
  useCallback,
  useEffect,
  useLayoutEffect,
  useRef,
  useState,
} from 'react'

export const Messages = () => {
  const userId = useUserId()

  const [isNewMessageOverlayVisible, setIsNewMessageOverlayVisible] =
    useState(false)

  // Tracks whether user is at bottom of the page, so that when new message comes in they're scrolled to it if they were at the bottom previously:
  const isAtBottomRef = useRef(true)
  // Once the user has scrolled, we don't want to fire virtualizer's onChange anymore as this could create weird jumps.
  const hasUserScrolledRef = useRef(false)
  const isProgrammaticScrollRef = useRef(false)

  const scrollContainerRef = useRef<HTMLDivElement>(null)
  /**
   * Using callback ref instead of a normal ref because it's the easiest way to get the scrollToBottom logic on mount.
   * Otherwise, the ref is null on mount, and scrollToBottom logic won't work.
   */
  const setScrollContainerRef = useCallback((el: HTMLDivElement | null) => {
    scrollContainerRef.current = el
    if (!el) return

    // Track scroll position so that we know whether to scroll to bottom when new messages arrive:
    const handleScroll = () => {
      // Keep track of whether user is at bottom of scroll container:
      const isScrolledToBottom = isAtBottom(el)
      // Close overlay whenever user reaches bottom of screen:
      if (isScrolledToBottom) setIsNewMessageOverlayVisible(false)
      isAtBottomRef.current = isScrolledToBottom
      // Don't want to set hasScrolledRef if the scroll was programmatic:
      if (isProgrammaticScrollRef.current) return
      hasUserScrolledRef.current = true
    }

    el.addEventListener('scroll', handleScroll)

    return () => el.removeEventListener('scroll', handleScroll)
  }, [])

  const {
    data: members,
    isPending: membersPending,
    error: membersError,
  } = useMembers()
  const messagesInfinite = useMessagesInfinite(1)
  const { data: messages = [], error, isPending } = messagesInfinite

  const itemSize = 80

  const getItemKey = useCallback(
    (index: number) => messages[index].messageId,
    [messages],
  )

  const virtualizer = useVirtualizer({
    count: messages.length,
    scrollMargin: 32,
    paddingStart: 32,
    paddingEnd: 32,
    // gap: 24,
    estimateSize: () => itemSize,
    overscan: 5,
    getItemKey,
    getScrollElement: () => scrollContainerRef.current,
  })

  virtualizer.shouldAdjustScrollPositionOnItemSizeChange = () => true

  const scrollToBottom = useCallback(
    (el: HTMLDivElement, behavior: 'instant' | 'smooth' = 'instant') => {
      isProgrammaticScrollRef.current = true
      // const { paddingStart, paddingEnd } = virtualizer.options
      // virtualizer.scrollToOffset(
      //   virtualizer.getTotalSize() + paddingStart + paddingEnd,
      //   {
      //     behavior,
      //     align: 'auto',
      //   },
      // )
      console.log('SCROLLING TO BOTTOM', el.scrollHeight)
      el.scrollTo({ top: el.scrollHeight, behavior })
      // Wrapping in animation frame ensures that isProgrammaticScrollRef isn't reset until after the scroll handler fires:
      requestAnimationFrame(() => {
        isProgrammaticScrollRef.current = false
      })
    },
    [],
  )

  const totalSize = virtualizer.getTotalSize()
  /**
   * Scroll to bottom on component mount.
   * Also re-scrolls to bottom every time totalSize changes. This happens as items are measured.
   * Once user scrolls, this effect is disabled. Realistically, this should fire several times right on mount, and never again.
   */
  useEffect(() => {
    if (hasUserScrolledRef.current || !scrollContainerRef.current) return
    scrollToBottom(scrollContainerRef.current)
  }, [totalSize, scrollToBottom])

  const prevScrollHeightRef = useRef(scrollContainerRef.current?.scrollHeight)
  const prevTotalSizeRef = useRef(virtualizer.getTotalSize())
  const prevFirstMessageRef = useRef(messages[0])
  const prevMessagesLengthRef = useRef(messages.length)
  useLayoutEffect(() => {
    const firstMessage = messages[0]
    // Determine whether new message was prepended (this means older messages were fetched, as opposed to newer ones being added via websockets).
    const isPrepended =
      prevFirstMessageRef.current &&
      prevFirstMessageRef.current.messageId !== firstMessage.messageId
    if (isPrepended) {
      // Animation frame because we need to wait for the scroll height to update.
      // Some notes because I know I'll forget this: In testing, scrollHeight was initially 3176.
      // After fetching more messages, it's 4376 for a second (delta=1200). That's with page size of 15 and estimateSize=80.
      // So I'm pretty sure that comes from (estimateSize * numNewMessages) = (80 * 15) = 1200.
      // But after being 4376 for a second, it updates to 4736. Pretty sure this is due to the elements getting measured.
      // Without the requestAnimationFrame, scrollTop is set to 1200 (using the estimated heights) but it needs to be set to 1560.
      // With the requestAnimationFrame, I guess it waits for scrollHeight to update to 4736, which gives us the correct delta of 1560.
      requestAnimationFrame(() => {
        if (!scrollContainerRef.current || !prevScrollHeightRef.current) return
        // const deltaTotalSize =
        //   virtualizer.getTotalSize() - prevTotalSizeRef.current
        // console.log(
        //   'TOTAL SIZE: ',
        //   deltaTotalSize,
        //   virtualizer.getTotalSize(),
        //   prevTotalSizeRef.current,
        // )
        // console.log('SCROLL OFFSET: ', virtualizer.scrollOffset)
        // if (virtualizer.scrollOffset != null) {
        //   console.log('OFFSET: ', virtualizer.scrollOffset + deltaTotalSize)
        //   virtualizer.scrollToOffset(virtualizer.scrollOffset + deltaTotalSize)
        // }

        const deltaScrollHeight =
          scrollContainerRef.current.scrollHeight - prevScrollHeightRef.current
        console.log(
          'DELTA SCROLL HEIGHT: ',
          deltaScrollHeight,
          scrollContainerRef.current.scrollHeight,
          prevScrollHeightRef.current,
        )

        scrollContainerRef.current.scrollTop = deltaScrollHeight
        // const deltaTotalSize =
        //   virtualizer.getTotalSize() - prevTotalSizeRef.current
        // console.log(
        //   'DELTA TOTAL SIZE: ',
        //   deltaTotalSize,
        //   virtualizer.getTotalSize(),
        //   prevTotalSizeRef.current,
        // )

        // if (deltaTotalSize > 0 && virtualizer.scrollOffset != null) {
        //   virtualizer.scrollToOffset(virtualizer.scrollOffset + deltaTotalSize)
        // }
      })
    } else {
      // If it's a new message, scroll to bottom so that the new message is in view, if user was already at bottom.
      // Also, if user sent the message, scroll to the bottom regardless.
      if (isAtBottomRef.current || messages.at(-1)?.sentBy === userId) {
        requestAnimationFrame(() => {
          if (!scrollContainerRef.current) return
          scrollToBottom(scrollContainerRef.current)
        })
      } else {
        // If user wasn't at bottom, show the new message overlay:
        setIsNewMessageOverlayVisible(true)
      }
    }
    // Update refs:
    prevFirstMessageRef.current = messages[0]
    prevMessagesLengthRef.current = messages.length
  }, [messages, virtualizer, scrollToBottom, userId])

  const handleNewMessageOverlayClick = useCallback(() => {
    const el = scrollContainerRef.current
    if (!el) return
    scrollToBottom(el)
  }, [scrollToBottom])

  if (isPending || membersPending) return <Loading className="bg-white" />
  if (error) throw error
  if (membersError) throw membersError

  console.log('TOTAL SIZE: ', virtualizer.getTotalSize())
  // console.log('SCROLL HEIGHT: ', scrollContainerRef.current?.scrollHeight)
  return (
    <div
      ref={setScrollContainerRef}
      className="grow w-full overflow-y-auto bg-white"
    >
      <InfiniteScrollSentinel
        type="next"
        infiniteQueryResult={messagesInfinite}
        onBeforeFetch={() => {
          prevTotalSizeRef.current = virtualizer.getTotalSize()
          prevScrollHeightRef.current = scrollContainerRef.current?.scrollHeight
        }}
      />
      <div>
        <div
          style={{
            height: `${virtualizer.getTotalSize()}px`,
            width: '100%',
            position: 'relative',
          }}
        >
          {virtualizer.getVirtualItems().map((item) => {
            const {
              content,
              sentAt,
              status,
              messageId,
              conversationId,
              sentBy,
            } = messages[item.index]
            const sender = members.find((member) => member.userId === sentBy)
            return (
              <div
                key={item.key}
                data-index={item.index}
                ref={virtualizer.measureElement}
                style={{
                  position: 'absolute',
                  top: 0,
                  left: 0,
                  width: '100%',
                  transform: `translateY(${
                    item.start - virtualizer.options.scrollMargin
                  }px)`,
                }}
              >
                <Message
                  key={item.index}
                  content={content}
                  senderName={sender?.displayName ?? 'Unknown'}
                  isUser={sender?.userId === userId}
                  sentAt={sentAt}
                  status={status}
                  messageId={messageId}
                  conversationId={conversationId}
                />
              </div>
            )
          })}
        </div>
      </div>
      {isNewMessageOverlayVisible && (
        <NewMessageOverlay onClick={handleNewMessageOverlayClick} />
      )}{' '}
    </div>
  )
}

/**
 * Checks if user is at bottom of scrollable element. Uses 60px as a buffer.
 */
const isAtBottom = (el: HTMLDivElement) => {
  return el.scrollHeight - el.scrollTop - el.clientHeight < 60
}

That's the general idea anyway. Figure out if the data was prepended and then shift the scrollTop accordingly. Mine's still not working consistently because I haven't gotten the shouldAdjustScrollPositionOnItemSizeChange logic sorted out. If you set it to true, it'll adjust correctly, but it causes other bugs elsewhere. But the upwards scroll is doing alright.