useVirtualList
A hook that efficiently renders large lists by only rendering items in or near the viewport.
useVirtualList
The useVirtualList
hook enables efficient rendering of large lists by only rendering items that are currently visible in the viewport (plus a few extra for smooth scrolling). This dramatically improves performance and reduces memory usage when working with lists containing hundreds or thousands of items.
Item 1
This is the description for item 1. It contains some information about the item.
Item 2
This is the description for item 2. It contains some information about the item.
Item 3
This is the description for item 3. It contains some information about the item.
Item 4
This is the description for item 4. It contains some information about the item.
Item 5
This is the description for item 5. It contains some information about the item.
Item 6
This is the description for item 6. It contains some information about the item.
Item 7
This is the description for item 7. It contains some information about the item.
Item 8
This is the description for item 8. It contains some information about the item.
Item 9
This is the description for item 9. It contains some information about the item.
Item 10
This is the description for item 10. It contains some information about the item.
Item 11
This is the description for item 11. It contains some information about the item.
Item 12
This is the description for item 12. It contains some information about the item.
Item 13
This is the description for item 13. It contains some information about the item.
Item 14
This is the description for item 14. It contains some information about the item.
Installation
Install the useVirtualList hook using:
File Structure
Parameters
Prop | Type | Default |
---|---|---|
items | T[] | Required |
options | VirtualListOptions | {} |
Options
Prop | Type | Default |
---|---|---|
itemHeight | number | ((index: number, item: T) => number) | Required |
overscan | number | 3 |
scrollingDelay | number | 150 |
scrollingResetTimespan | number | 150 |
useIsScrolling | boolean | false |
Return Value
Prop | Type | Default |
---|---|---|
virtualItems | Array<{ index: number, start: number, end: number, item: T }> | - |
totalHeight | number | - |
isScrolling | boolean | - |
scrollToIndex | (index: number, options?: { align?: 'auto' | 'start' | 'center' | 'end' }) => void | - |
Examples
Virtual Grid Layout
Creating a virtual grid for efficiently rendering large sets of items in a grid layout:
Dynamic Height Items
Handle items with varying heights:
Infinite Loading List
Combine virtual list with infinite loading:
Use Cases
- Long Lists: Tables, feeds, logs, search results with many items
- Data Grids: Tables with many rows
- Chat Interfaces: Message logs in chat applications
- Infinite Scrolling: Continuously loading content as user scrolls
- Product Catalogs: E-commerce product listings
- File Browsers: Long directory listings
- Music/Video Libraries: Media player track listings
- Documentation: Long articles or documentation with fixed-position navigation
- User Directories: Contact lists or user management interfaces
- Timeline Views: Chronological data displays
Performance Benefits
Virtual lists offer significant performance advantages:
- Reduced DOM Size: Only renders what’s visible, not the entire list
- Improved Initial Load Time: No need to process all list items at once
- Smooth Scrolling: Less work per frame means better scrolling performance
- Lower Memory Usage: Fewer DOM nodes in memory at any time
- Better React Reconciliation: Fewer components to compare and update
Accessibility Considerations
- Ensure proper keyboard navigation through the virtualized content
- Maintain focus position when scrolling or updating content
- Provide appropriate ARIA attributes for list structures
- Consider the impact of dynamic content loading on screen readers
- Test with assistive technologies to verify a good experience
Browser Support
The hook relies on standard browser features for scrolling and positioning that work across all modern browsers.
Common Challenges and Solutions
Scroll Restoration
When navigating away and back, maintain scroll position:
Scroll to Specific Item
Use the scrollToIndex
function returned by the hook:
Working with Forms
When rendering forms in virtual lists, be careful with form state:
Best Practices
- Optimize Item Rendering: Keep item components simple and efficient
- Memoize Expensive Calculations: Use React.memo and useMemo appropriately
- Use Stable Item Heights: For best performance, use consistent item heights when possible
- Measure Dynamically When Needed: For varying heights, implement a measuring system
- Customize Overscan: Adjust overscan based on your use case and scrolling speed
- Handle Window Resizing: Update calculations when container dimensions change
- Consider Keyboard Navigation: Add support for keyboard-based scrolling
- Cache Item Data: Minimize recalculations when items don’t change
- Use Virtualization Selectively: Don’t add complexity for small lists (< 100 items)
- Test Performance: Monitor render times and memory usage during development