feat: support caching dynamic measurements by unique key (#107)

* feat: support caching measurements by unique key

* Run Prettier

* Update docs

Author: mattmikolay

README.md

@@ -284,6 +284,10 @@ const {
  - `scrollOffsetFn: Function() => number`
    - Optional
    - This function, if passed, is called on scroll to get the scroll offest rather than using `parentRef`'s `width` or `height`
+- `keyExtractor: Function(index) => String | Integer`
+  - Optional
+  - This function receives the index of each item and should return the item's unique ID.
+  - This function should be passed whenever dynamic measurement rendering is enabled and the size or order of items in the list changes.
 
 ### Returns
 

src/index.js

@@ -4,6 +4,7 @@ import useRect from './useRect'
 import useIsomorphicLayoutEffect from './useIsomorphicLayoutEffect'
 
 const defaultEstimateSize = () => 50
+const defaultKeyExtractor = index => index
 
 export function useVirtual({
   size = 0,
@@ -17,6 +18,7 @@ export function useVirtual({
   useObserver,
   onScrollElement,
   scrollOffsetFn,
+  keyExtractor = defaultKeyExtractor,
 }) {
   const sizeKey = horizontal ? 'width' : 'height'
   const scrollKey = horizontal ? 'scrollLeft' : 'scrollTop'
@@ -47,23 +49,20 @@ export function useVirtual({
 
   const [measuredCache, setMeasuredCache] = React.useState({})
 
-  const measure = React.useCallback(
-    () => setMeasuredCache({}),
-    []
-  )
+  const measure = React.useCallback(() => setMeasuredCache({}), [])
 
   const measurements = React.useMemo(() => {
     const measurements = []
     for (let i = 0; i < size; i++) {
-      const measuredSize = measuredCache[i]
+      const measuredSize = measuredCache[keyExtractor(i)]
       const start = measurements[i - 1] ? measurements[i - 1].end : paddingStart
       const size =
         typeof measuredSize === 'number' ? measuredSize : estimateSize(i)
       const end = start + size
       measurements[i] = { index: i, start, size, end }
     }
     return measurements
-  }, [estimateSize, measuredCache, paddingStart, size])
+  }, [estimateSize, measuredCache, paddingStart, size, keyExtractor])
 
   const totalSize = (measurements[size - 1]?.end || 0) + paddingEnd
 
@@ -78,10 +77,14 @@ export function useVirtual({
 
   const element = onScrollElement ? onScrollElement.current : parentRef.current
   useIsomorphicLayoutEffect(() => {
-    if (!element) { return }
+    if (!element) {
+      return
+    }
 
     const onScroll = () => {
-      const scrollOffset = scrollOffsetFn ? scrollOffsetFn() : element[scrollKey]
+      const scrollOffset = scrollOffsetFn
+        ? scrollOffsetFn()
+        : element[scrollKey]
       latestRef.current.scrollOffset = scrollOffset
       setRange(prevRange => calculateRange(latestRef.current, prevRange))
     }
@@ -121,7 +124,7 @@ export function useVirtual({
 
               setMeasuredCache(old => ({
                 ...old,
-                [i]: measuredSize,
+                [keyExtractor(i)]: measuredSize,
               }))
             }
           }
@@ -132,16 +135,23 @@ export function useVirtual({
     }
 
     return virtualItems
-  }, [range.start, range.end, measurements, sizeKey, defaultScrollToFn])
+  }, [
+    range.start,
+    range.end,
+    measurements,
+    sizeKey,
+    defaultScrollToFn,
+    keyExtractor,
+  ])
 
   const mountedRef = React.useRef()
 
   useIsomorphicLayoutEffect(() => {
     if (mountedRef.current) {
-      if (estimateSize || size) setMeasuredCache({})
+      if (estimateSize) setMeasuredCache({})
     }
     mountedRef.current = true
-  }, [estimateSize, size])
+  }, [estimateSize])
 
   const scrollToOffset = React.useCallback(
     (toOffset, { align = 'start' } = {}) => {
@@ -192,8 +202,8 @@ export function useVirtual({
         align === 'center'
           ? measurement.start + measurement.size / 2
           : align === 'end'
-            ? measurement.end
-            : measurement.start
+          ? measurement.end
+          : measurement.start
 
       scrollToOffset(toOffset, { align, ...rest })
     },
@@ -224,19 +234,20 @@ export function useVirtual({
   }
 }
 
-function calculateRange({
-  overscan,
-  measurements,
-  outerSize,
-  scrollOffset,
-}, prevRange) {
+function calculateRange(
+  { overscan, measurements, outerSize, scrollOffset },
+  prevRange
+) {
   const total = measurements.length
   let start = total - 1
   while (start > 0 && measurements[start].end >= scrollOffset) {
     start -= 1
   }
   let end = 0
-  while (end < total - 1 && measurements[end].start <= scrollOffset + outerSize) {
+  while (
+    end < total - 1 &&
+    measurements[end].start <= scrollOffset + outerSize
+  ) {
     end += 1
   }
 

types/index.d.ts

@@ -1,45 +1,46 @@
-type ScrollAlignment = 'start' | 'center' | 'end' | 'auto'
-
-interface ScrollToOptions {
-  align: ScrollAlignment
-}
-
-interface ScrollToOffsetOptions extends ScrollToOptions {}
-interface ScrollToIndexOptions extends ScrollToOptions {}
-
-export type VirtualItem = {
-  index: number
-  start: number
-  end: number
-  size: number
-  measureRef: React.RefObject<any>
-}
-
-declare function useVirtual<T>(options: {
-  size: number
-  parentRef: React.RefObject<T>
-  estimateSize?: (index: number) => number
-  overscan?: number
-  horizontal?: boolean
-  scrollToFn?: (
-    offset: number,
-    defaultScrollToFn?: (offset: number) => void
-  ) => void
-  paddingStart?: number
-  paddingEnd?: number
-  useObserver?: (
-    ref: React.RefObject<T>
-  ) => {
-    width: number
-    height: number
-    [key: string]: any
-  }
-}): {
-  virtualItems: VirtualItem[]
-  totalSize: number
-  scrollToOffset: (index: number, options?: ScrollToOffsetOptions) => void
-  scrollToIndex: (index: number, options?: ScrollToIndexOptions) => void
-  measure: () => void
-}
-
-export { useVirtual }
+type ScrollAlignment = 'start' | 'center' | 'end' | 'auto'
+
+interface ScrollToOptions {
+  align: ScrollAlignment
+}
+
+interface ScrollToOffsetOptions extends ScrollToOptions {}
+interface ScrollToIndexOptions extends ScrollToOptions {}
+
+export type VirtualItem = {
+  index: number
+  start: number
+  end: number
+  size: number
+  measureRef: React.RefObject<any>
+}
+
+declare function useVirtual<T>(options: {
+  size: number
+  parentRef: React.RefObject<T>
+  estimateSize?: (index: number) => number
+  overscan?: number
+  horizontal?: boolean
+  scrollToFn?: (
+    offset: number,
+    defaultScrollToFn?: (offset: number) => void
+  ) => void
+  paddingStart?: number
+  paddingEnd?: number
+  useObserver?: (
+    ref: React.RefObject<T>
+  ) => {
+    width: number
+    height: number
+    [key: string]: any
+  }
+  keyExtractor?: (index: number) => number | string
+}): {
+  virtualItems: VirtualItem[]
+  totalSize: number
+  scrollToOffset: (index: number, options?: ScrollToOffsetOptions) => void
+  scrollToIndex: (index: number, options?: ScrollToIndexOptions) => void
+  measure: () => void
+}
+
+export { useVirtual }