Implementation:TobikoData Sqlmesh VirtualList

Knowledge Sources	TobikoData_Sqlmesh
Domains	Web_UI, Components, Performance
Last Updated	2026-02-07 20:00 GMT

Overview

A virtualized list component using TanStack Virtual that efficiently renders large lists by only mounting visible items.

Description

The VirtualList component implements virtual scrolling using @tanstack/react-virtual to handle large datasets efficiently. It only renders items currently visible in the viewport plus a small buffer, dramatically reducing DOM node count and improving performance. The component includes a scroll-to-selected button that appears when the active item is outside the visible range, providing easy navigation back to selected items. It uses useVirtualizer hook with configurable estimated item height for size calculations and supports smooth scrolling animations. The list maintains absolute positioning for virtual items and uses CSS containment for performance optimization.

Usage

Use VirtualList for rendering large collections (hundreds to thousands of items) where rendering all items would cause performance issues. Provide an accurate estimatedListItemHeight for best performance. The isSelected callback enables the scroll-to-selected feature. This component is essential for model lists, log viewers, or any large dataset display in the SQLMesh UI.

Code Reference

Source Location

Repository: TobikoData_Sqlmesh
File: web/common/src/components/VirtualList/VirtualList.tsx

Signature

export interface VirtualListProps<TItem> {
  items: TItem[]
  estimatedListItemHeight: number
  renderListItem: (
    item: TItem,
    virtualItem?: VirtualItem,
    virtualizer?: Virtualizer<HTMLDivElement, Element>,
  ) => React.ReactNode
  isSelected?: (item: TItem) => boolean
  className?: string
}

export function VirtualList<TItem>({
  items,
  estimatedListItemHeight,
  renderListItem,
  isSelected,
  className,
}: VirtualListProps<TItem>) {
  // Implementation
}

Import

import { VirtualList } from '@sqlmesh-common/components/VirtualList/VirtualList'

I/O Contract

Inputs

Name	Type	Required	Description
items	TItem[]	Yes	Array of items to render
estimatedListItemHeight	number	Yes	Approximate height of each item in pixels
renderListItem	(item: TItem, virtualItem?: VirtualItem, virtualizer?: Virtualizer) => React.ReactNode	Yes	Function to render each item
isSelected	(item: TItem) => boolean	No	Function to determine if item is selected (enables scroll-to button)
className	string	No	Additional CSS classes for container

Outputs

Name	Type	Description
element	React.ReactElement	Scrollable container with virtualized list

Usage Examples

// Basic virtual list
<VirtualList
  items={largeDataset}
  estimatedListItemHeight={40}
  renderListItem={(item) => (
    <div className="h-10 p-2 border-b">
      {item.name}
    </div>
  )}
/>

// With selection tracking
<VirtualList
  items={models}
  estimatedListItemHeight={56}
  isSelected={(model) => model.id === selectedModelId}
  renderListItem={(model) => (
    <ModelListItem
      model={model}
      onClick={() => setSelectedModelId(model.id)}
    />
  )}
/>

// Using virtual item metadata
<VirtualList
  items={logEntries}
  estimatedListItemHeight={32}
  renderListItem={(entry, virtualItem, virtualizer) => (
    <div
      data-index={virtualItem?.index}
      style={{ height: virtualItem?.size }}
    >
      [{entry.timestamp}] {entry.message}
    </div>
  )}
/>

// Complex list with variable heights
interface DataRow {
  id: string
  content: string
  expanded: boolean
}

<VirtualList<DataRow>
  items={rows}
  estimatedListItemHeight={60}
  renderListItem={(row) => (
    <div className={row.expanded ? 'h-32' : 'h-16'}>
      <DataCard data={row} />
    </div>
  )}
  isSelected={(row) => row.id === activeRowId}
  className="h-screen"
/>

Technical Details

Virtual Scrolling Mechanics

Uses useVirtualizer hook from TanStack Virtual
Calculates visible range based on scroll position
Only renders items within visible range plus overscan buffer
Updates virtual items array on scroll events
Maintains scroll container ref for position calculations

Scroll-to-Selected Feature

The component automatically: 1. Tracks the index of the selected item using isSelected callback 2. Checks if selected index is outside visible range 3. Shows "Scroll to selected" button when outside range 4. Scrolls with smooth animation when button clicked 5. Centers selected item in viewport using align: 'center'

Performance Optimization

CSS containment: Uses contain: 'strict' for layout optimization
Absolute positioning: Virtual items positioned absolutely with transform
Minimal re-renders: Only visible items re-render on scroll
Estimated sizing: Reduces initial measurement overhead

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment