How we optimized rendering performance while handling thousands of annotations in React — Part 2

In the first part of this series, we shared how our Nutrient Web Viewer SDK struggled with the same core challenge many React apps face: rendering performance at scale. When handling documents with thousands of annotations, noticeable lag occurred during zooming, panning, and other interactions. We used React Profiler and browser performance dev tools to pinpoint the bottlenecks. By deferring heavy tasks out of the render cycle, avoiding costly shallow copies, applying memoization, and offloading work to web workers, we made the user interface (UI) far more responsive and stable under heavy load.

But the problem remains: Rendering at this scale is still demanding, and our improvements were just the first step. In this followup, we’ll continue addressing the same challenge and share how we pushed performance further, with techniques and architectural changes you can apply to your own large-scale React applications.

Identifying the culprit

The first step in solving this problem was figuring out which components were rerendering unnecessarily.

We started with the excellent React Scan(opens in a new tab) library. It gave us a high-level view of which components were being redrawn and how often. That was extremely helpful, but only up to a point. Some of our components are fairly complex, with multiple nested custom hooks, and React Scan doesn’t always show why a rerender happened. We encountered the same issue with React Developer Tools; however, it was fixed(opens in a new tab) in the meantime.

To dig deeper, we wrote our own debugging hook to log the exact props that triggered a rerender. It worked like a diff, comparing the previous props with the current ones and printing out what changed.

Here’s a small custom hook we used:

function useLogWhyRendered<T extends Record<string, any>>(
  props: T,
  name: string = "Component"
): void {
  const prevProps = useRef<T>(props)

  useEffect(() => {
    const changedProps: { key: keyof T; prev: T[keyof T]; next: T[keyof T] }[] = []

    for (const key in props) {
      if (props[key] !== prevProps.current[key]) {
        changedProps.push({
          key,
          prev: prevProps.current[key],
          next: props[key],
        })
      }
    }

    if (changedProps.length > 0) {
      console.groupCollapsed(`${name} props changed:`)
      changedProps.forEach(({ key, prev, next }) => {
        console.log(
          `${String(key)} changed:`,
          "\nOld:",
          prev,
          "\nNew:",
          next
        )
      })
      console.groupEnd()
    }

    prevProps.current = props
  })
}

With this hook in place, we could finally see why React thought it needed to rerender. Often, it turned out to be something as subtle as passing down an object or function reference that was recreated on every render.

Research and solution: Targeted rerenders

The solution was simple in theory but required careful analysis: Ensure components only rerender when absolutely necessary.

Here’s how we approached it.

1. Stable references

One of the biggest lessons we learned was how crucial stable references are in React.

React compares props shallowly, meaning it only checks if references are the same, but not if the contents are equal. If you pass a new object, array, or function every time a component renders, React assumes it changed, even if the internal values haven’t.

This problem often hides in plain sight. The most common culprits are callbacks, inline style objects, or JSX children created on the fly.

And yes, this might sound like React 101. Most developers know about reference equality, but in practice, it’s surprisingly easy to get wrong. All it takes is one unstable dependency in a useCallback or useMemo hook to quietly invalidate memoization and trigger a cascade of rerenders.

Paying close attention to which values your hooks depend on and avoiding passing whole objects when only one property matters can make a huge difference in rendering performance:

// ❌ Causes rerenders every time.
<AnnotationItem style={{ color: 'red' }} onClick={() => handleClick(id)} />

// ✅ Keeps references stable.
const style = useMemo(() => ({ color: 'red' }), [])
const handleClickStable = useCallback(() => handleClick(id), [id])

<AnnotationItem style={style} onClick={handleClickStable} />

2. Correct dependency selection

Memoization is only effective when the right dependencies are chosen, and those dependencies should be as minimal as possible. This was particularly important for us because our SDK uses Immutable.js(opens in a new tab) in our global state.

Immutable.js guarantees that any update creates a new object reference, even if only a small part of the object has changed. This means that if we passed the entire annotation object as a dependency to useMemo or useCallback, any update to any property on any annotation would cause the hook to rerun, even if the part of the object we actually cared about hadn’t changed.

To fix this, we selected only the properties we actually needed from the annotation object:

const content = useMemo(
  () => getAnnotationContent(annotation.id, annotation.type),
  [annotation.id, annotation.type]
)

By narrowing the dependencies to just annotation.id and annotation.type, we prevented unnecessary recalculations whenever other fields of the annotation changed. This dramatically reduced wasted work and kept rendering focused on truly relevant changes.

3. Optimizing Redux’s useSelector

Many of our components used Redux’s useSelector to pull derived values from state. The issue? Every store update triggered rerenders, even when the underlying data didn’t change.

The root cause was that useSelector relies on reference equality to determine if the selected value has changed. That means any selector returning a new object or array on each call — for example, from .filter() or .map() — will always cause a rerender:

// ❌ New array every time → always rerenders.
const visibleAnnotations = useSelector(state =>
  state.annotations.filter(a => a.visible)
)

To avoid this, ensure your selector returns the same reference when the underlying data hasn’t changed. One easy fix is to compute derived values inside a useMemo that depends only on the relevant slice of state:

function useVisibleAnnotations() {
  const annotations = useSelector(state => state.annotations)

  return useMemo(
    () => annotations.filter(a => a.visible),
    [annotations]
  )
}

If your selector needs to return an object — for example, bundling several related fields together — consider using the shallowEqual comparison function to help useSelector detect when the actual content is the same:

// ✅ Avoids rerender if object fields didn't change.
const annotationInfo = useSelector(
  state => ({
    count: state.annotations.length,
    visibleCount: state.annotations.filter(a => a.visible).length,
  }),
  shallowEqual
)

Now, React only rerenders when the relevant state truly changes, and not just because of a new object or array reference.

In short: useSelector sees references only, not values. Returning stable values (or comparing them shallowly when needed) can eliminate thousands of unnecessary renders and make your app feel dramatically smoother.

The result

After implementing targeted rerenders:

• Hovering over an annotation no longer triggered rerenders for all annotations.
• Toolbar updates were isolated to actual changes in toolbar state.
• CPU usage dropped dramatically, and interactions became smooth again, even with thousands of annotations on a single page.

It was a classic case of “less is more,” quite literally. By carefully controlling what triggered rerenders, we transformed a sluggish UI into a responsive experience.