Migration guide for version 2.x upgrade

[lperry25]

Summary

Upgrading from react-window v1 to v2 is confusing without a consolidated migration guide. In v1 we used FixedSizeList / VariableSizeList and the child render function; in v2 there’s a unified List with a rowComponent prop and new prop/type names. I’m not finding a single place that explains the exact mappings (components, props, and TS types), so the upgrade generates a lot of TypeScript errors and guesswork.

Docs I found

• Releases show a small upgrade snippet (uses List, rowComponent, rowCount, rowHeight, rowProps), but it doesn’t cover the common v1 surfaces (variable-size, horizontal lists, scroll/resize handlers, height, width etc.). 
• README points to the docs site, but there isn’t a dedicated migration page that covers the above in one place.

Requested migration content

1. Component mapping

• FixedSizeList → List (fixed-size)
• VariableSizeList → List (variable-size)

2. Prop mapping (Lists)

• itemCount → rowCount
• itemSize (number) → rowHeight (number) for fixed-size
• Horizontal lists: document the v2 prop(s) to replace layout="horizontal" (if applicable)
• Sizing (previous height & width props)

[vtlnkhn]

@lperry25 Agreed. I’ve used v1 for large lists with DnD, and it worked perfectly. I’m trying to migrate to v2, but it doesn’t seem to work at all. I probably missed something—having a migration guide would be helpful.

Update: I just found a solution in the closed issues, and now v2 works perfectly too. That said, a migration guide is still needed.

[bvaughn]

Sorry folks, but I’m not going to write a guide. I just don’t have the time.

If you’d like to write one, I can review it briefly and merge it so that it’s in the repo here in the form of a read me or something, but that’s the only way it will get written.

[aldenquimby]

@vtlnkhn can you link to the closed issue you're referring to? I am trying to upgrade to v2 and failing. I cannot figure out how to replicate the old listRef.current?.resetAfterIndex(index, true);. So far I've got:

Before:

<VariableSizeList
  ref={listRef}
  height={menuHeight}
  itemCount={elements.length}
  itemSize={getItemSize}
  overscanCount={2}
>
  {(props) => (
    <MyOption {...props} {...myCustomProps}>
      {elements[props.index]}
    </MyOption>
  )}
</VariableSizeList>

After:

<List
  listRef={listRef}
  defaultHeight={menuHeight}
  rowCount={elements.length}
  rowHeight={getItemSize}
  overscanCount={2}
  rowProps={{ ...myCustomProps, elements }}
  rowComponent={MyOption}
  // also refactor MyOption to do `elements[index]` instead of accepting children
/>

Before:

const listRef = useRef<VariableSizeList>(null);

listRef.current?.scrollToItem(index, 'smart');

After:

const listRef = useListRef(null);

listRef.current?.scrollToRow({ index, align: 'smart' });

But without resetAfterIndex I can't really test our app

[bvaughn]

You shouldn’t need to call resetAfterIndex in version two. List and Grid handle their own memoization automatically now.

[aldenquimby]

@bvaughn we have a variable size list, where the height of each element is only known after rendering. v2 appears to still be using absolute positioning with transform: translateY to top offset each row. If row 9 ends up being 35px high, but that's only known after rendering row 9, how can I tell react-window to re-calculate the offset needed for all rows after 9? Previously we used resetAfterIndex for this

[bvaughn]

I think you would need to pass a size cache (Map of index to height?) via rowProps, then List would auto invalidate itself.

I hope to support this natively “soon” for what it’s worth (#830)

Note the size cache should be immutable.

[vtlnkhn]

@aldenquimby that issue would not be helpful in your case

[jkincheloe33]

I think you would need to pass a size cache (Map of index to height?) via rowProps, then List would auto invalidate itself.
@bvaughn

I am getting this to partially work, but my size cache has to undergo multiple changes based on different APIs being called. This works on initial load for me, but whenever pairing with the new react-window-infinite-loader, the new items don't get properly sized unless I trigger a top level state change to force the component to re-render.

I have my size cached store like this const itemSize = useMemo(() => () => {}, []), which always worked for v1 with resetAfterIndex. Now it only works for the initial batch, then the new rows are stuck at my fallback height.

<List
  listRef={listRef}
  onRowsRendered={onRowsRendered}
  overscanCount={5}
  rowCount={loadMore ? feedItems.length + 1 : feedItems.length}
  rowHeight={index => itemSize[index] ?? 186}
  rowProps={{ items: feedItems, itemSize }}
  rowComponent={({ index, style }: RowComponentProps) => {
    return feedItems[index] ? <div style={style}>{getContent({ index, isScrolling: false })}</div> : <div style={style} />
  }}
/>

[bvaughn]

Please share a StackBlitz or Code Sandbox link to a repro and I’ll take a look.

I have my size cached store like this const itemSize = useMemo(() => () => {}, []), which always worked for v1 with resetAfterIndex. Now it only works for the initial batch, then the new rows are stuck at my fallback height.

I will say that this looks like a buggy cache, if sizes might change. Mutable values won't trigger re-renders in React (and even if they did, things that are memoized using them may not be recreated). This library expects rowProps to change along with conditions that might affect rows (and it invalidates its own cached sizes and offsets accordingly).

If you wanted to be extra performance sensitive, you could only partially recreate your own cache (e.g. if you wanted to save rows before a certain index and only clear ones after that– that's okay) but List/Grid expects an updated prop when underlying conditions change.

[bvaughn]

Taking a pass at this with PR #848; formatted README can be seen here:

https://github.com/bvaughn/react-window/blob/migration-code/CHANGELOG.md#upgrade-path

I'll add some basic examples (lists, grids) on the train ride this evening, then I'll close this issue as complete. If there are more, specific examples that you'd like to see added– please open PRs with them! 🙇🏼