Events & Callbacks

Callbacks available for responding to virtual list events.

onLoadMore

Triggered when the user scrolls near the end of the list. Used for implementing infinite scroll / pagination.

Signature

onLoadMore?: () => void | Promise<void>

onLoadMore?: () => void | Promise<void>

Example

<script lang="ts">
    import VirtualList from '@humanspeak/svelte-virtual-list'

    let items = $state([...initialItems])
    let hasMore = $state(true)
    let isLoading = $state(false)

    async function loadMore() {
        if (isLoading) return
        isLoading = true

        try {
            const newItems = await fetchMoreItems()
            items = [...items, ...newItems]

            if (newItems.length === 0) {
                hasMore = false
            }
        } finally {
            isLoading = false
        }
    }
</script>

<VirtualList
    {items}
    onLoadMore={loadMore}
    {hasMore}
    loadMoreThreshold={10}
>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</VirtualList>

<script lang="ts">
    import VirtualList from '@humanspeak/svelte-virtual-list'

    let items = $state([...initialItems])
    let hasMore = $state(true)
    let isLoading = $state(false)

    async function loadMore() {
        if (isLoading) return
        isLoading = true

        try {
            const newItems = await fetchMoreItems()
            items = [...items, ...newItems]

            if (newItems.length === 0) {
                hasMore = false
            }
        } finally {
            isLoading = false
        }
    }
</script>

<VirtualList
    {items}
    onLoadMore={loadMore}
    {hasMore}
    loadMoreThreshold={10}
>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</VirtualList>

When a load adds nothing

If a load finishes without adding items — an empty page, or a request that fails — the list does not call onLoadMore again straight away. It asks again when:

new items arrive — the list gets longer, or its first or last item changes (for example, data arrives from somewhere else),
the user scrolls away from the end of the list and back, or
hasMore is set to false and then back to true, which you can use for a retry button.

Set hasMore to false once there is no more data.

If you build new item objects on every update (for example items={rows.map(toRow)}), set itemKey. The list then compares items by key, so it can still tell that an empty page added nothing.

Related Props

Prop	Description
`hasMore`	Set to `false` to stop triggering `onLoadMore`
`loadMoreThreshold`	Items from end to trigger (default: 20)

debugFunction

Receive real-time debug information about the list state.

Signature

debugFunction?: (info: SvelteVirtualListDebugInfo) => void

debugFunction?: (info: SvelteVirtualListDebugInfo) => void

Example

<script lang="ts">
    import VirtualList from '@humanspeak/svelte-virtual-list'
    import type { SvelteVirtualListDebugInfo } from '@humanspeak/svelte-virtual-list'

    function onDebug(info: SvelteVirtualListDebugInfo) {
        // Track scroll position
        if (info.atBottom) {
            console.log('User reached the bottom')
        }

        // Monitor performance
        console.log(`Rendering ${info.visibleItemsCount} of ${info.totalItems} items`)
    }
</script>

<VirtualList
    {items}
    debug={true}
    debugFunction={onDebug}
>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</VirtualList>

<script lang="ts">
    import VirtualList from '@humanspeak/svelte-virtual-list'
    import type { SvelteVirtualListDebugInfo } from '@humanspeak/svelte-virtual-list'

    function onDebug(info: SvelteVirtualListDebugInfo) {
        // Track scroll position
        if (info.atBottom) {
            console.log('User reached the bottom')
        }

        // Monitor performance
        console.log(`Rendering ${info.visibleItemsCount} of ${info.totalItems} items`)
    }
</script>

<VirtualList
    {items}
    debug={true}
    debugFunction={onDebug}
>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</VirtualList>

Debug Info Properties

Property	Type	Description
`startIndex`	`number`	First rendered item index
`endIndex`	`number`	Last rendered item index
`totalItems`	`number`	Total items in list
`visibleItemsCount`	`number`	Currently visible items
`processedItems`	`number`	Items with measured heights
`averageItemHeight`	`number`	Calculated average height
`atTop`	`boolean`	Scrolled to top
`atBottom`	`boolean`	Scrolled to bottom
`totalHeight`	`number`	Total content height