elementslist

List

Headless collection renderer with polymorphic roots and caller-controlled virtualization.

Import#

import { List } from 'moraine'
import { useListVirtualizer } from 'moraine/utils'

List owns collection traversal and the scroll-element bridge used by virtual renderers. Item markup, semantics, styling, filtering, focus, and selection remain under caller control.

Examples#

Object List#

Render arbitrary objects with a semantic ul root, role="list", and data-slot="root" by default. Use as and native root attributes when another element or role is required; explicit attributes override the defaults.

1
function Basic() {
2
  return (
3
    <List
4
      items={JOBS}
5
      aria-label="Open positions"
6
      class="border border-border rounded-md divide-border divide-y"
7
      itemRender={(context) => (
8
        <li class="p-3 flex gap-3 items-center justify-between">
9
          <span class="flex flex-col min-w-0">
10
            <span class="font-medium">{context.item.title}</span>
11
            <span class="text-sm text-muted-foreground">{context.item.team}</span>
12
          </span>
13
          <span class="text-xs text-muted-foreground shrink-0">{context.item.location}</span>
14
        </li>
15
      )}
16
    />
17
  )
18
}

Virtualization#

Import useListVirtualizer from moraine/utils. It provides a ready-to-use virtualRender, automatically connects the scroll element, positions rows, and forwards dynamic measurement refs. Configure estimateSize, a stable getItemKey, and optional TanStack Virtual settings such as gap and overscan.

The built-in adapter requires @tanstack/virtual-core as an optional peer dependency. Install a compatible version in your application before using it.

bun add @tanstack/virtual-core

Provide a custom virtualRender component when the built-in absolute row layout is not suitable.

1
function Virtualization() {
2
  const ITEMS = Array.from({ length: 10_000 }, (_, index) => ({
3
    id: index + 1,
4
    label: `Result ${index + 1}`,
5
  }))
6

7
  type Item = (typeof ITEMS)[number]
8

9
  const virtualizer = useListVirtualizer<Item, HTMLElement, HTMLDivElement>({
10
    estimateSize: () => 36,
11
    getItemKey: (item) => item.id,
12
    overscan: 8,
13
  })
14

15
  return (
16
    <List
17
      as="div"
18
      items={ITEMS}
19
      virtualRender={virtualizer.virtualRender}
20
      role="list"
21
      aria-label="Virtual results"
22
      class="border border-border rounded-md h-72 w-full overflow-y-auto"
23
      itemRender={(context) => (
24
        <div {...context.props} role="listitem">
25
          <div class="px-3 border-b border-border flex h-9 items-center">{context.item.label}</div>
26
        </div>
27
      )}
28
    />
29
  )
30
}

Dynamic Heights#

For variable-height rows, provide a reasonable estimate and let the built-in renderer measure connected rows. TanStack Virtual observes later content size changes and recalculates positions; gap remains consistent between measured rows.

1
function DynamicHeight() {
2
  const ITEMS = Array.from({ length: 1_000 }, (_, index) => ({
3
    id: index + 1,
4
    label: `Result ${index + 1}`,
5
    details: Array.from(
6
      { length: (index % 4) + 1 },
7
      (_, detailIndex) => `Detail line ${detailIndex + 1} for result ${index + 1}.`,
8
    ),
9
  }))
10

11
  type Item = (typeof ITEMS)[number]
12

13
  const virtualizer = useListVirtualizer<Item, HTMLElement, HTMLDivElement>({
14
    estimateSize: () => 96,
15
    getItemKey: (item) => item.id,
16
    gap: 8,
17
    overscan: 8,
18
  })
19

20
  return (
21
    <List
22
      as="div"
23
      items={ITEMS}
24
      virtualRender={virtualizer.virtualRender}
25
      role="list"
26
      aria-label="Variable-height results"
27
      class="py-2 border border-border rounded-md h-80 w-full overflow-y-auto"
28
      itemRender={(context) => (
29
        <div {...context.props} role="listitem">
30
          <div class="mx-2 px-3 py-2 border border-border rounded-md">
31
            <div class="font-medium">{context.item.label}</div>
32
            <div class="text-sm text-muted-foreground">
33
              <For each={context.item.details}>
34
                {(detail) => <span class="block">{detail}</span>}
35
              </For>
36
            </div>
37
          </div>
38
        </div>
39
      )}
40
    />
41
  )
42
}

API Reference#

Props#

Prop	Type	Default	Description
as	`T \| undefined`	`ul`	Root element or component.
class	`ClassValue`	—	Class applied to the component root or trigger element.
classes	`ListT.Classes \| undefined`	—	—
itemRender*	`ComponentOrElement<ListT.ItemRenderProps<TItem, TItemElement>>`	—	Renders one collection item.
items	`readonly TItem[] \| undefined`	—	Reactive collection rendered by the list.
ref	`JSX.HTMLElementTags[T] extends { ref?: infer Ref; } ? Ref : never \| undefined`	—	—
style	`JSX.CSSProperties \| undefined`	—	—
styles	`ListT.Styles \| undefined`	—	—
virtualRender	`Component<ListT.VirtualRenderProps<TItem, HTMLElement, TItemElement>> \| undefined`	—	Replaces normal iteration with caller-controlled virtual rendering.

ARIA#

Accessibility attributes and roles emitted by the component markup.

Attribute	Type	Default	Description
role	`string`	—	Defines the semantic role exposed to assistive technology.

Data Attributes#

State and slot attributes exposed for styling hooks and selectors.

Attribute	Type	Default	Description
data-slot	`string`	—	Identifies the rendered slot for styling hooks and selectors.