Skip to content

feat: implement virtualized list for large dataset display (#175) - #185

Merged
elizabetheonoja-art merged 1 commit into
Utility-Protocol:mainfrom
Chigybillionz:feature/175-virtual-list
Aug 20, 2026
Merged

feat: implement virtualized list for large dataset display (#175)#185
elizabetheonoja-art merged 1 commit into
Utility-Protocol:mainfrom
Chigybillionz:feature/175-virtual-list

Conversation

@Chigybillionz

Copy link
Copy Markdown
Contributor

**Close #175

Summary of the issue
Displaying large datasets (thousands of meter readings) in the current UI causes significant performance degradation and lag. Rendering the entire list at once locks the main thread, resulting in poor scroll performance and an unresponsive user experience.

Root cause
The application currently renders every row of the dataset directly into the DOM regardless of whether it is visible in the viewport. For datasets exceeding a few hundred items, this overwhelms the browser's rendering engine and consumes excessive memory.

Solution implemented
Implemented a windowed/virtualized rendering strategy that only renders the DOM nodes currently visible in the viewport (plus a small overscan buffer to prevent flickering). As the user scrolls, rows are recycled and repositioned using GPU-accelerated CSS transforms (translateY), ensuring smooth scrolling even with 10,000+ items.

Key changes made

  • Created useVirtualList hook (src/hooks/useVirtualList.ts) for robust state management, supporting:
    • Dynamic row heights using a ResizeObserver-like measurement approach per row.
    • Scroll position restoration using sessionStorage (perfect for when users navigate away and back).
    • Infinite scroll pagination hooks (onLoadMore triggers).
  • Built a presentational VirtualList component (src/components/ui/VirtualList.tsx) that consumes the hook and handles ARIA accessibility, empty states, and loading indicators.
  • Added optimized CSS (src/styles/virtual-list.css) with strict CSS containment (contain: strict/layout) to isolate the rendering cost of the list from the rest of the page.
  • Added comprehensive unit and component tests (tests/hooks/useVirtualList.test.ts and tests/components/VirtualList.test.tsx) covering large dataset efficiency, measurements, and state handling.

Any trade-offs or considerations

  • Initial Scroll Bar Accuracy: Because row heights can be dynamic and calculated just-in-time when rendered, the scroll bar's total height is initially based on an estimatedItemHeight. If the estimate is wildly inaccurate, the scrollbar might "jump" as the user scrolls. I've set a sensible default of 48px, which can be overridden per list.
  • Dependency Free: Opted to write a custom virtual list from scratch instead of pulling in external libraries like react-virtual to keep bundle size minimal and tailored precisely to the project's state architecture.

Testing steps (how to verify the fix)

  1. Check out this branch and run the application (npm run dev).
  2. Navigate to a dashboard or view that utilizes the large dataset (e.g., thousands of meter readings).
  3. Observe that the initial page load is practically instantaneous.
  4. Scroll rapidly through the list. Note that scrolling is completely smooth at 60fps.
  5. Inspect the DOM via browser DevTools: you should only see a handful of virtual-list-row DOM nodes that update their translateY position dynamically instead of thousands of nodes.
  6. Verify accessibility features (e.g. aria-rowcount, aria-label) are appropriately passed to screen readers.
  7. Run the test suite (npm run test) to verify the new virtual list tests pass.

Please kindly review this task. If there are any corrections, improvements, adjustments, or merge conflicts that you notice regarding my implementation, I'd really appreciate your feedback. I'd also love to hear your overall review of my work on this branch.
Thank you!

@elizabetheonoja-art
elizabetheonoja-art merged commit 8956c75 into Utility-Protocol:main Aug 20, 2026
9 of 10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Virtualized List for Large Dataset Display

2 participants