DreamLake

VirtualList

Renders only the visible slice of a large list. Supports fixed item heights, dynamic (content-driven) heights, and infinite scroll.

Fixed height

Pass itemHeight as a number (px).

Item 1
Item 2
Item 3
Item 4

Dynamic height

Pass itemHeight="dynamic" for content-driven heights. Each item is measured after it renders. Use estimatedItemHeight to set the initial layout estimate.

Item 1 — This item has a longer description that wraps onto multiple lines to demonstrate dynamic height measurement.
Item 2
Item 3
Item 4

Infinite scroll

Pass hasMore, loadingMore, and onLoadMore. The callback fires when the scroll position is within loadMoreThreshold px (default 80) of the bottom.

Showing 30 / 200

Item 1
Item 2
Item 3
Item 4

Experiment selection

useListSelection is the selection controller extracted from DreamLake's experiment list. Combine it with VirtualList or useVirtualList; it does not render rows or replace your focus/navigation behavior.

Click or drag to replace. Cmd/Ctrl adds; Shift selects a range. Tab then Enter selects a row; Escape clears.

No experiments selected
GestureSelection behavior
Plain clickReplace with that row and move the range anchor.
Cmd/Ctrl clickToggle that row and move the anchor.
Shift clickReplace with the inclusive anchor-to-row range, in list order.
Plain drag across rowsReplace with the crossed range. A press alone does nothing until click.
Cmd/Ctrl dragAdd the crossed range to the selection captured at the press.
EscapeClear selection; dialog-owned or prevented Escape is left alone.

The hook keeps selected record snapshots supplied by the caller. Additive selection retains existing objects, including off-list records; replacing the selection discards them. Reversing a drag recomputes from its press-time baseline, so its range can shrink. Use stable id strings and pass rows in displayed order. The range anchor is an index, matching the experiment list. If the displayed row order changes during a gesture, call cancelDrag() and set a new anchor if needed.

tsx
import { useListSelection, useVirtualList } from "@dreamlake/uikit/list";

const selection = useListSelection({
  selected, // controlled records with string ids
  onSelectionChange: setSelected, // omit for read-only
  resetKey: projectAndFolder, // changing context clears the selection
  listenForEscape: false, // handle Escape in the focused list instead
});

The focused /list entrypoint exports these two hooks and their types without loading component, editor, or icon modules. useListSelection is also exported from the package root.

Bind handleRowClick(index, rows, event) and either the mouse handlers handleRowMouseDown/handleRowMouseEnter or their pointer equivalents. Pointer adapters ignore touch drags so native touch scrolling can continue; the resulting tap is handled by click. Window release ends a gesture; blur, pointer cancellation, unmount and resetKey changes discard stale gesture state. Neither row handlers nor global listeners prevent default scrolling or capture the pointer for you.

For a virtualized list with pointer capture or autoscroll, extend a drag through handleRowMouseEnter(index, rows, { buttons: 1 }) using its current row index. Call endDrag() on normal release before forwarding the gesture's click; it preserves suppression of a completed drag's click. Use cancelDrag() only for cancellation. Do not also forward the retargeted native click after manually forwarding one. clear() and selectAll(rows) serve toolbar actions; toggle(index, rows) supports keyboard toggling, and setAnchor(index, rows) moves a keyboard range anchor without selecting. Shift keyboard ranges use the same handleRowClick method with shiftKey: true.

selected and onSelectionChange form the controlled contract: render from the selected records and update them in the callback. resetKey defaults to undefined; listenForEscape defaults to true for the existing application behavior. Multiple same-turn calls read the preceding proposed selection, so batched toggles retain all changes. Omitting the callback makes every mutation read-only while preserving isSelected(id).

Props

PropTypeDefaultDescription
itemsT[]—Array of items to render.
itemHeightnumber | "dynamic"—Fixed height in px, or "dynamic" for content-driven heights.
estimatedItemHeightnumber40Initial height estimate used in dynamic mode.
heightnumber | string"100%"Container height.
overscannumber3Extra items rendered outside the visible area.
getItemKey(item, index) => string | numberindexReturns a stable key for each item.
children(item, index, style) => ReactNode—Render function. Must apply style to the item root element.
hasMorebooleanfalseWhether more items can be loaded.
loadingMorebooleanfalseShows a loading indicator at the bottom while true.
onLoadMore() => void—Called when scroll reaches the load-more threshold.
loadMoreThresholdnumber80Px from bottom that triggers onLoadMore.
renderLoadingMoreReactNode"Loading more…"Custom content shown while loadingMore is true.
onScroll(scrollTop: number) => void—Fires on scroll with the current scrollTop value.
onRangeChange(start, end) => void—Fires when the visible index range changes.
stickyHeaderReactNode—Header rendered inside the scroll container with position: sticky. Only shown when stickyHeaderHeight is greater than 0.
stickyHeaderHeightnumber0Height of stickyHeader. Subtracted from visible-area calculations so items don't render under it.
classNamestring—Extra classes on the container.