FAQ and troubleshooting

The list is blank

Check that the viewport has a real height or width, itemCount is greater than zero, and all three layout bindings are attached with the required nesting. Use how virtual layout works to compare roles, then compare the component with the simple-list example for its framework.

Rows jump when they are first shown

The initial estimate differs from the measured border-box size. Choose a closer estimatedItemSize and verify that every mounted item uses the adapter’s item binding with its current index. See measurement and dynamic sizes.

Why does every item need a ref, directive, or attachment?

Core must associate a ResizeObserver measurement with a collection index. The framework binding supplies that association and cleans it up when the item unmounts. Do not replace it with a manual layout read in the item renderer.

A sorted or prepended row lost its local state

Pass getItemKey to the framework list renderer, or use the record identifier as the key in a Svelte each block. Index keys identify a position, not a record, so framework-local state cannot follow data that moves. The TanStack Table examples show keyed sorting and filtering; the prepend examples show index and scroll-position changes together.

Why did a live feed stop following new messages?

That should happen after the user scrolls away from the latest item. Preserve their position and offer an explicit jump back instead of forcing the viewport down. Use the tested live-feed implementation.

Can headers and footers be inside the viewport?

Yes. Place them beside the total-size spacer and attach sticky elements through the model when they reserve viewport space. Keep the rendered window inside the spacer. See the sticky header and footer example.

Do example CSS classes have to be copied?

No. Presentation is application-owned. The viewport still needs a usable size, and application styles must not overwrite the layout-owned size, position, or transform properties listed in render ownership.

Is server-side rendering supported?

Yes. Estimates create the initial range before DOM attachment and measured sizes replace them after hydration. See support and compatibility and the adapter’s working example rather than maintaining separate server markup.

How many items are supported?

The limit is high enough for millions of items, but browser CSS dimensions and application memory usually become practical constraints first. The exact core limit, memory rationale, and browser-layout caveat live in

.