Duncan Leung
Tackling 'on load' Scrolling in Chat Applications
Published on

Tackling 'on load' Scrolling in Chat Applications

Authors

I encountered a frustrating scrolling user experience in our chat platform that was occurring due to a race condition of images loading within the chat, and a scroll-to-bottom function.

Ideally, when a chat loads, the UI should automatically scroll to the latest messages. However, when there are images in the chat history, the scroll wouldn't reach the end of the chat due to the timing of asynchronous image loading, DOM updates, and scroll positioning.

The Problem: Auto-Scrolling Fails When Images Load

Our React app has a chat interface where users can share images and text messages. While the auto-scroll worked fine for text messages, there was an annoying issue: when the chat history contained an image, the chat UI would initially scroll to show the latest message, but as soon as the images loaded (which expands the content height), the view would remain at an earlier point in the conversation instead of keeping the latest message visible.

Original Approach: IntersectionObserver

Our initial implementation relied on React's rendering cycle and the IntersectionObserver API to detect when images appeared in the viewport:

// Initial implementation with IntersectionObserver
useEffect(() => {
  if (!hasScrolledOnFirstLoad.current && latestChatMessageEle.current && messages?.length && messages.length > 0) {
    latestChatMessageEle.current.scrollIntoView({
      block: 'end',
    });

    // Set up an observer to handle image loading and maintain scroll position
    const imageObserver = new IntersectionObserver(
      (entries) => {
        entries.forEach((entry) => {
          if (entry.isIntersecting) {
            const img = entry.target as HTMLImageElement;

            const handleImageLoad = () => {
              if (
                latestChatMessageEle.current &&
                messagesContainerEle.current &&
                isAtBottom(messagesContainerEle.current)
              ) {
                latestChatMessageEle.current.scrollIntoView({
                  block: 'end',
                  behavior: 'smooth',
                });
              }
            };

            if (img.complete) {
              handleImageLoad();
            } else {
              img.addEventListener('load', handleImageLoad);
            }

            imageObserver.unobserve(img);
          }
        });
      },
      { threshold: 0.1 },
    );

    // Find all images in the messages container
    const chatImages = messagesContainerEle.current?.querySelectorAll('img');
    if (chatImages && chatImages.length > 0) {
      chatImages.forEach((img) => imageObserver.observe(img));
    }

    hasScrolledOnFirstLoad.current = true;

    return () => {
      imageObserver.disconnect();
      const chatImages = messagesContainerEle.current?.querySelectorAll('img');
      if (chatImages) {
        chatImages.forEach((img) => img.removeEventListener('load', () => {}));
      }
    };
  }
}, [messages]);

Why It Didn't Work

This approach had several issues:

  1. Timing Problems: The IntersectionObserver only observes elements that are already in the DOM. If images are loaded dynamically or rendered after this code runs, they won't be observed.

  2. Observer Lifecycle: We were observing images only on the first load, but new images could be added at any time.

  3. Event Listener Cleanup: The cleanup function wasn't correctly removing the specific handleImageLoad callbacks, potentially causing memory leaks.

  4. Scroll State Management: The approach didn't account for different scroll behaviors in various scenarios, like switching between chat threads or handling multiple images loading asynchronously.

  5. Direct DOM Manipulation: We were directly calling scrollIntoView() without considering the browser's rendering lifecycle, which can cause timing issues.

The Solution: MutationObserver and Multi-layered Scrolling

After debugging extensively, we discovered a more robust approach combining several techniques:

  1. A dedicated scroll function with requestAnimationFrame
  2. MutationObserver to detect DOM changes (particularly image loads)
  3. Multiple scheduled scroll attempts with different timings
  4. Better state tracking for different chat scenarios

The Core Solution

Here's a breakdown of the main components that made it work:

1. The Core Scroll Function

We created a dedicated forceScrollToBottom function that uses requestAnimationFrame to ensure it runs after the browser has updated the layout:

/**
 * CRITICAL FUNCTION: Reliably scrolls chat to the bottom
 */
const forceScrollToBottom = useCallback((behavior: ScrollBehavior = 'auto') => {
  if (!messagesContainerEle.current || !latestChatMessageEle.current) return;

  // Using requestAnimationFrame ensures the scroll happens after rendering
  requestAnimationFrame(() => {
    if (latestChatMessageEle.current) {
      latestChatMessageEle.current.scrollIntoView({
        block: 'end',
        behavior,
      });
    }
  });
}, []);

2. MutationObserver for DOM Changes

The most critical improvement was using MutationObserver to detect changes in the DOM, especially when images load:

// Create a new observer that will monitor DOM changes
const observer = new MutationObserver((mutations) => {
  // Look for image-related mutations or significant height changes
  const hasRelevantChanges = mutations.some((mutation) => {
    // Check for new nodes
    if (mutation.type === 'childList' && mutation.addedNodes.length > 0) {
      return true;
    }

    // Check for attribute changes on images - critical for detecting when images finish loading
    if (
      mutation.type === 'attributes' &&
      mutation.target instanceof HTMLImageElement &&
      mutation.attributeName === 'src'
    ) {
      return true;
    }

    return false;
  });

  if (hasRelevantChanges && messagesContainerEle.current) {
    console.log('[DEBUG] Mutation observer detected relevant changes, scrolling to bottom');
    forceScrollToBottom('smooth');
  }
});

// Configure and start the observer - these settings ensure we catch image loads
observer.observe(messagesContainerEle.current, {
  childList: true,  // Detect when elements are added or removed
  subtree: true,    // Look at all descendants, not just direct children
  attributes: true, // Monitor attribute changes (like src on images)
  attributeFilter: ['src', 'style', 'class'], // Only these specific attributes
});

3. Multiple Scheduled Scroll Attempts

We implemented a multi-layered approach with several scheduled scroll attempts to handle edge cases:

// Multi-layered approach: Schedule scrolls at different intervals as a fallback
// This ensures we catch images that load at different times
setTimeout(() => forceScrollToBottom(), 100);
setTimeout(() => forceScrollToBottom('smooth'), 500);
setTimeout(() => forceScrollToBottom('smooth'), 1500);
setTimeout(() => forceScrollToBottom('smooth'), 3000);

4. Better State Management

We improved state tracking with multiple refs to handle different scenarios:

const initialLoadCompleteRef = useRef(false);
const lastCaseRef = useRef<string | null>(null);
const hasScrolledOnFirstLoad = useRef(false);
const mutationObserverRef = useRef<MutationObserver | null>(null);

The Complete Solution

When we put these pieces together, we created a robust system that:

  1. Detects when images load through DOM changes
  2. Schedules scrolling at appropriate times
  3. Ensures consistent behavior across different chat scenarios
  4. Properly cleans up resources to prevent memory leaks

Why It Works: Technical Deep Dive

The reason our solution works so well is that it addresses the fundamental issues with image loading in web applications:

1. The Browser Rendering Pipeline

When images load, browsers go through several phases:

  • Layout recalculation
  • Paint
  • Composite

By using requestAnimationFrame, we ensure our scroll code executes after these phases are complete, which gives us more predictable behavior.

2. Event-Based vs. Observation-Based Approaches

Our previous approach relied on specific events (load on images), but the new approach observes the DOM itself for changes. This is more robust because:

  • It catches any DOM changes, not just specific events
  • It works even if images are added dynamically after initial render
  • It can respond to various types of content changes, not just images

3. Race Conditions

The multiple scheduled scrolls help address race conditions where images might load at different times. Instead of relying on a single scroll attempt, we have multiple opportunities to ensure the chat is properly scrolled.

4. Browser-Specific Behavior

Different browsers handle image loading and layout calculations differently. Our approach is more resilient to these differences by using standard Web APIs (MutationObserver, requestAnimationFrame) that are consistently implemented across browsers.

Practical Takeaways

If you're implementing a chat interface or any UI with dynamic content loading, here are the key lessons:

  1. Use MutationObserver for content changes: It's more reliable than event listeners for tracking when content changes the layout.

  2. Schedule UI updates with requestAnimationFrame: This ensures your code runs at the right time in the browser's rendering cycle.

  3. Implement multiple layers of protection: Don't rely on a single approach - combine immediate actions with scheduled fallbacks.

  4. Track state carefully: Use refs to maintain state across renders and different scenarios.

  5. Debug with console logs: Strategic logging helps identify exactly when and why scrolling issues occur.

Conclusion

Handling image loading in chat interfaces is a challenging problem that requires understanding both React's component lifecycle and the browser's rendering process. By combining MutationObserver, requestAnimationFrame, and a multi-layered approach to scrolling, we created a robust solution that ensures users always see the latest messages, even when they contain images.

This pattern can be applied to many similar UI challenges where asynchronous content loading affects layout and user experience. The key is to work with the browser's rendering cycle rather than against it, and to implement multiple layers of protection against edge cases.

Discuss on Twitter • View on GitHub