logo svelte /virtual list v0.5.2

Scroll Methods

You can programmatically scroll to any item in the list using the scroll method. This is useful for jump-to-item navigation, search results, and more.

Interactive Demo

file · ScrollToItemExample.svelte mode · live running open source
● ready
Item 0 first
Item 1 scroll target
Item 2 scroll target
Item 3 scroll target
Item 4 scroll target
Item 5 scroll target
Item 6 scroll target
Item 7 scroll target
Item 8 scroll target
Item 9 scroll target
Item 10 scroll target
Item 11 scroll target
Item 12 scroll target
Item 13 scroll target
Item 14 scroll target
Item 15 scroll target
Item 16 scroll target
Item 17 scroll target
Item 18 scroll target
Item 19 scroll target
Item 20 scroll target
target · 5000
align · auto
range · 0-0
dom rows · 0
dom nodes · 0

Basic Usage

To use the scroll method, bind a reference to the VirtualList component:

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

    let listRef

    const items = Array.from({ length: 10000 }, (_, i) => ({
        id: i,
        text: `Item ${i}`
    }))

    function goToItem5000() {
        listRef.scroll({
            index: 5000,
            smoothScroll: true,
            align: 'auto'
        })
    }
</script>

<button onclick={goToItem5000}>
    Scroll to item 5000
</button>

<VirtualList {items} bind:this={listRef}>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</VirtualList>
<script lang="ts">
    import VirtualList from '@humanspeak/svelte-virtual-list'

    let listRef

    const items = Array.from({ length: 10000 }, (_, i) => ({
        id: i,
        text: `Item ${i}`
    }))

    function goToItem5000() {
        listRef.scroll({
            index: 5000,
            smoothScroll: true,
            align: 'auto'
        })
    }
</script>

<button onclick={goToItem5000}>
    Scroll to item 5000
</button>

<VirtualList {items} bind:this={listRef}>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</VirtualList>

API Reference

scroll(options)

Scrolls the list to bring a specific item into view.

scroll(options: {
    index: number
    smoothScroll?: boolean
    shouldThrowOnBounds?: boolean
    align?: 'auto' | 'top' | 'bottom' | 'nearest'
})
scroll(options: {
    index: number
    smoothScroll?: boolean
    shouldThrowOnBounds?: boolean
    align?: 'auto' | 'top' | 'bottom' | 'nearest'
})

Options

OptionTypeDefaultDescription
indexnumberRequiredThe item index to scroll to (0-based)
smoothScrollbooleantrueUse smooth scrolling animation
shouldThrowOnBoundsbooleantrueThrow error if index is out of bounds
alignstring'auto'Where to align the item in the viewport

Alignment Options

  • 'auto' (default) - Only scroll if the item is not visible. Aligns to top or bottom as appropriate.
  • 'top' - Always align the item to the top of the viewport.
  • 'bottom' - Always align the item to the bottom of the viewport.
  • 'nearest' - Scroll as little as possible to bring the item into view (like native scrollIntoView({ block: 'nearest' })).

Examples

Scroll to specific index

<button onclick={() => listRef.scroll({ index: 500 })}>
    Go to item 500
</button>
<button onclick={() => listRef.scroll({ index: 500 })}>
    Go to item 500
</button>

Scroll without animation

<button onclick={() => listRef.scroll({ index: 500, smoothScroll: false })}>
    Jump to item 500 (instant)
</button>
<button onclick={() => listRef.scroll({ index: 500, smoothScroll: false })}>
    Jump to item 500 (instant)
</button>

Always align to top

<button onclick={() => listRef.scroll({ index: 500, align: 'top' })}>
    Scroll to item 500 (top aligned)
</button>
<button onclick={() => listRef.scroll({ index: 500, align: 'top' })}>
    Scroll to item 500 (top aligned)
</button>

Minimal scrolling

<button onclick={() => listRef.scroll({ index: 500, align: 'nearest' })}>
    Scroll to item 500 (nearest)
</button>
<button onclick={() => listRef.scroll({ index: 500, align: 'nearest' })}>
    Scroll to item 500 (nearest)
</button>

TypeScript

For full type safety, you can type the ref:

type ListRef = {
    scroll: (options: {
        index: number
        smoothScroll?: boolean
        shouldThrowOnBounds?: boolean
        align?: 'auto' | 'top' | 'bottom' | 'nearest'
    }) => void
}

let listRef: ListRef | undefined = $state(undefined)
type ListRef = {
    scroll: (options: {
        index: number
        smoothScroll?: boolean
        shouldThrowOnBounds?: boolean
        align?: 'auto' | 'top' | 'bottom' | 'nearest'
    }) => void
}

let listRef: ListRef | undefined = $state(undefined)

Or import the types from the package:

import type {
    SvelteVirtualListScrollOptions,
    SvelteVirtualListScrollAlign
} from '@humanspeak/svelte-virtual-list'
import type {
    SvelteVirtualListScrollOptions,
    SvelteVirtualListScrollAlign
} from '@humanspeak/svelte-virtual-list'