VirtualList

When to useLink to "When to use"

• Long lists of files, log lines, search results or history, where people pick one or several rows or open one.

Use something else when:

• the list is short (under a few hundred rows): Select, RadioGroup or a plain list
• rows nest: Tree (which windows the same way with virtual)
• rows have columns: Table
• people reorder rows: SortableList

UsageLink to "Usage"

import { VirtualList } from "@arshad-shah/cynosure";

<VirtualList
  label="Files"
  items={files}
  getKey={(file) => file.id}
  renderItem={(file) => file.name}
  onAction={(file) => open(file)}
/>

Rows share one height, set by CSS and measured, so keep each row to a line or a fixed layout. Set the list's height with style={{ blockSize: … }} or the height token.

ReorderingLink to "Reordering"

Give onMove to let people reorder, such as the pages of a document. Alt+Up/Down moves the chosen rows (or the focused row) one place; a mouse or pen drags them, with a line where they will land, scrolling near the edges, and Escape to cancel. Chosen rows move together. moveItems applies a move to your items.

<VirtualList
  label="Pages"
  items={pages}
  getKey={(p) => p.id}
  renderItem={(p) => p.name}
  selectionMode="multiple"
  onMove={(keys, to) => setPages(moveItems(pages, keys, to, (p) => p.id))}
/>

Logs and sectionsLink to "Logs and sections"

wrap lets rows wrap and grow (each row is measured), and follow keeps the end in view as rows arrive while people are reading the latest. handle scrolls from outside: scrollToIndex(index, { align }) ("nearest", the default, "start" or "center", as ScrollArea's scrollIntoView) and scrollToEnd().

const log = useRef<VirtualListHandle>(null);
<VirtualList label="Requests" items={lines} getKey={(l) => l.id} renderItem={(l) => l.text} selectionMode="none" wrap follow handle={log} />
<Button onClick={() => log.current?.scrollToEnd()}>Latest</Button>

onAtBottomChange reports when the view leaves the end (someone scrolled up to read) and comes back. overlay sits over the bottom centre of the list, outside the listbox, and does not scroll: put a "3 new" pill or a "Latest" button there that calls handle.scrollToEnd().

<VirtualList
  label="Activity"
  items={events}
  getKey={(e) => e.id}
  renderItem={(e) => e.text}
  selectionMode="none"
  follow
  handle={log}
  onAtBottomChange={setAtBottom}
  overlay={!atBottom && unseen > 0 && <Button onClick={() => log.current?.scrollToEnd()}>{`${unseen} new`}</Button>}
/>

isHeader marks rows that head a section (a date, a folder). They cannot be focused or chosen, and the current section's heading stays pinned at the top while its rows scroll under it.

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

• Role: a listbox named by label; rows are options with aria-posinset and aria-setsize, so a screen reader says "File 3, 3 of 10,000".
• Focus: one tab stop, on the chosen row or the first. The focused row is always rendered, so focus survives scrolling.

• Pointer: a click chooses (toggles with multiple); a double-click acts.
• Touch: rows are 44px tall on touch screens; a tap chooses.
• Empty: with no items the list shows empty and is no longer a listbox.

ThemingLink to "Theming"

Tokens: --cy-virtual-list-height, --cy-virtual-list-row-height, --cy-virtual-list-selected-background. The overlay is placed by OverlayFrame (--cy-overlay-frame-offset, --cy-overlay-frame-layer).

RelatedLink to "Related"

ScrollArea · Tree · Table · SortableList