Virtualized List Rendering#

Element Web uses a layered virtualization stack—built on react-virtuoso—to efficiently render large room and member lists. The primitives live in packages/shared-components/src/core/VirtualizedList/ 1 and are consumed by VirtualizedRoomListView in packages/shared-components/src/room-list/VirtualizedRoomListView/ 2.

Scope note: The shared components described here power the new room list (Element Web). The legacy MemberList component in matrix-react-sdk uses a separate, simpler approach covered in the Legacy section below.

Core Abstractions#

FlatVirtualizedList and GroupedVirtualizedList were split from the original ListView / VirtualizedList in PR #31860 and PR #32566 respectively.

Overscan / Viewport Extension#

To avoid blank "black spots" during fast scroll, both lists extend their rendered viewport beyond the visible area via Virtuoso's increaseViewportBy prop 3:

• Room list: EXTENDED_VIEWPORT_HEIGHT = 25 × ROOM_LIST_ITEM_HEIGHT (52px) = 1300px above and below 4 — introduced in PR #30867.
• Member list (legacy MemberListView): EXTENDED_VIEWPORT_HEIGHT = 15 × MEMBER_LIST_ITEM_HEIGHT (56px) = 840px — introduced in PR #31198.

The overscan buffer eliminates most blank-space artifacts at moderate scroll speeds; very fast "sling" scrolling can still reveal gaps 3.

Range Mapping#

In grouped mode, Virtuoso counts section headers as list entries, so its rangeChanged indices are in entry space, not room space. VirtualizedRoomListView maps between the two via mapEntryRangeToRoomRange() before calling vm.updateVisibleRooms() 5. Without this conversion, nearly every scroll event incorrectly destroyed and recreated room view models — the bug fixed in PR #34112.

Similarly, useVirtualizedList exposes two optional props for callers to declare their own index-space translation 6:

• mapScrollIndex — converts an items-array index to Virtuoso's scroll index (used by scrollToIndex)
• mapRangeIndex — converts Virtuoso's reported range index back to items-array index (applied in handleRangeChanged)

Touch Gesture Handling#

The DragDropProvider (via @dnd-kit/react) wraps the grouped room list. The PointerSensor uses device-aware activation constraints 7:

• Touch (pointerType === "touch"): Delay({ value: 250, tolerance: 5 }) — drag starts only after a 250ms hold; any earlier finger movement cancels the drag, allowing normal scroll.
• Mouse / pen: Distance({ value: 5 }) — drag starts after a 5px movement.

This resolved issues #34372 and #34402 where touch-scrolling the room list opened context menus or failed entirely 8.

Grouped List: Pinned Headers#

GroupedVirtualizedList renders section headers in two layers 9:

1. Real headers inside the virtualized stream (CSS position: sticky) — accessible and focusable.
2. Sticky overlay rendered outside the stream (renderStickyHeader prop) — stays visible when the real header scrolls out of the virtualized render window.

An updateSticky callback tracks which group is topmost by reading scrollTop and comparing rendered item offsets; getScrollPaddingTop returns 0 for header items (so they land flush at the top) and the header height for room items (to clear the overlay) during keyboard navigation 10 11.

Items and headers are interleaved into a single NavigationEntry<Header, Item> discriminated-union array for unified keyboard navigation 12.

Legacy: TruncatedList + MemberList#

Before the new virtualized stack, the legacy MemberList component (in matrix-react-sdk) used a simpler approach:

• TruncatedList (src/components/views/elements/TruncatedList.tsx) renders up to truncateAt children and calls createOverflowElement with a count of hidden items. It does not virtualize — it simply slices the child array 13.
• MemberList starts with truncateAtJoined = 30 and truncateAtInvited = 5, expanding by 100 on each "show more" click 14. It delegates actual member loading and sorting to MemberListStore.

MemberListStore (src/stores/MemberListStore.ts) handles lazy loading:

• If lazy loading is disabled or the room is already loaded (loadedRooms set), members are read directly from room.currentState 15.
• Otherwise it calls room.loadMembersIfNeeded() (with storage) or fetches from /members directly (Sliding Sync / incognito mode) 16.
• Once loaded, the room ID is cached in loadedRooms to prevent redundant network requests 17.
• Members are sorted by: presence → power level → last active timestamp → display name 18.