perf-virtual-lists_skill

Overview

This skill specializes in high-performance list virtualization for Android TV apps built with React. It focuses on delivering smooth 60FPS scrolling on low-end TV boxes by using lightweight virtualization, TV-specific optimizations, and predictable layout strategies. The guidance targets movie and episode grids where large datasets and fast directional navigation are common.

How this skill works

It uses react-window with react-virtualized-auto-sizer to render only visible cells and a small overscan buffer, minimizing DOM nodes and paint work. The approach enforces fixed item sizes, lazy image loading, and a focus-index-driven navigation model so focus remains stable even when items unmount off-screen. Combined, these tactics avoid layout thrashing and preserve responsiveness on constrained TV hardware.

When to use it

• Large collections of posters or tiles (hundreds to thousands) in Android TV UIs.
• Layouts where users navigate quickly via D-pad (holding Down/Up).
• Cases where consistent 60FPS is required on low-memory TV boxes (e.g., 1GB RAM).
• Grid or list layouts where item dimensions can be fixed ahead of time.
• When image-heavy cards risk causing layout shifts during scroll.

Best practices

• Prefer FixedSizeList or FixedSizeGrid; avoid variable-size virtualization to prevent per-frame layout recalculation.
• Set overscanRowCount/overscanCount to at least 2–3 rows for TV to avoid blank regions during fast scrolls.
• Manage focus by tracking a focusedIndex in JS (useTVNavigation pattern) rather than relying on document.activeElement.
• Give images explicit width and height, use loading="lazy" or a FadeInImage that sets src only when inView.
• Keep item components lightweight: avoid heavy CSS effects and inline render functions; hoist renderers where possible.

Example use cases

• A movie grid showing thousands of posters where users navigate with a remote and expect instant responsiveness.
• An episode list with fixed-height rows and fast vertical paging where overscan prevents blank frames.
• A home screen carousel of recommended content using FixedSizeGrid to maintain smooth D-pad scrolling.
• A NAS media browser with image-heavy tiles that uses lazy loading and fixed sizes to avoid layout shifts.