List
Render caller-defined rows with optional virtual scrolling.
- Review onboarding designsElena
- Fix invoice roundingMarcus
- Draft 0.9 release notesPriya
Anatomy#
Usage#
Use List when the caller owns each row’s markup and needs a stable collection surface. Pass items
and an itemRender component; List does not take row content through children. Add a
virtualizer for large collections only when ordinary rendering becomes costly.
Row ownership#
itemRender receives the item, its index in the full collection, and, with a virtualizer,
row props. Spread props onto the outer row element; the virtualizer needs them for positioning
and measurement. The root is a <ul> by default and always has role="list", so render list-item
semantics in each row, or choose another root with as. TypeScript infers the item and root
element types from items and as. emptyRender renders when items is empty or undefined.
Virtualization#
createListVirtualizer is an optional adapter from moraine/virtualizer and needs
@tanstack/virtual-core. The List root is the scroll container, so give it a bounded height and
overflow-y-auto. Row count and scroll behavior follow the estimated or measured row sizes.
Read the Virtualization guide for setup, row measurements, stable keys, and keyboard navigation.
Load more at the edges#
onTopReached and onBottomReached fire once each time scrolling reaches the top or bottom edge
of an overflowing list; neither fires for the initial position. Combine onBottomReached with
scrollThreshold to request the next page shortly before the end.
Drag to reorder#
createListSortable is an optional adapter from moraine/dnd and needs @dnd-kit/dom. List has
no drag props; the sortable composes through itemRender. Wrap the list in sortable.Provider,
call sortable.useRow(context) in itemRender, and spread row.props onto the row element.
Update the items from onReorder.
row.props keeps the virtual row props from context.rowProps and adds the drag ref,
data-dragging, and data-drop-position. With a virtualizer, also pass
rangeExtractor: sortable.rangeExtractor to createListVirtualizer so the dragged row stays
mounted while it is scrolled out of view. Read the Drag and drop guide for
handles, keyboard dragging, and options.
Examples#
Clear an inbox to an empty state#
emptyRender renders when items is empty. List does not invent empty copy; pass the row markup you
want shown.
Scroll a large search result set#
Use createListVirtualizer when tens of thousands of rows would otherwise mount at once. Spread
context.rowProps onto the measured row element.
Reorder a checklist from a grip handle#
The grip button is the drag handle, so it also starts a keyboard drag with Space or Enter. Arrow keys move to the next row, and Space, Enter, or Escape ends the drag.
Reorder a long virtual playlist#
Drag a row toward the list edge to scroll. The row is its own handle here.
Render result rows with extra detail lines#
Estimate a larger size when row height varies, and let the virtualizer measure after mount.
API Reference#
Props#
Renders a <ul> element by default.