Methods
Programmatic control methods available on the VirtualList component.
Getting a Reference
Use Svelte’s bind:this to get a component reference:
<script lang="ts">
import VirtualList from '@humanspeak/svelte-virtual-list'
let listRef: VirtualList
</script>
<VirtualList bind:this={listRef} {items}>
{#snippet renderItem(item)}
<div>{item.text}</div>
{/snippet}
</VirtualList><script lang="ts">
import VirtualList from '@humanspeak/svelte-virtual-list'
let listRef: VirtualList
</script>
<VirtualList bind:this={listRef} {items}>
{#snippet renderItem(item)}
<div>{item.text}</div>
{/snippet}
</VirtualList>scroll()
Scroll to a specific item by index.
Signature
scroll(options: SvelteVirtualListScrollOptions): Promise<void>scroll(options: SvelteVirtualListScrollOptions): Promise<void>The returned promise resolves once the scroll has visually finished and the
list has re-rendered for the new position. For a smooth scroll it waits for the
native scrollend event (or, where unsupported, until the scroll position
settles); for an instant scroll it resolves after the DOM updates.
Options
| Property | Type | Default | Description |
|---|---|---|---|
index | number | required | Target item index |
smoothScroll | boolean | true | Use smooth scroll animation |
align | 'auto' \| 'top' \| 'bottom' \| 'nearest' \| 'center' | 'auto' | Alignment of target item |
shouldThrowOnBounds | boolean | true | Throw error if index out of bounds |
Examples
Scroll to item 100:
await listRef.scroll({ index: 100 })await listRef.scroll({ index: 100 })Scroll to top of list:
await listRef.scroll({ index: 0, align: 'top' })await listRef.scroll({ index: 0, align: 'top' })Scroll to bottom:
await listRef.scroll({ index: items.length - 1, align: 'bottom' })await listRef.scroll({ index: items.length - 1, align: 'bottom' })Center an item in the viewport:
await listRef.scroll({ index: 500, align: 'center' })await listRef.scroll({ index: 500, align: 'center' })Instant scroll (no animation):
await listRef.scroll({ index: 500, smoothScroll: false })await listRef.scroll({ index: 500, smoothScroll: false })Alignment Options
| Value | Behavior |
|---|---|
'auto' | Minimal scroll to make item visible |
'top' | Align item to top of viewport |
'bottom' | Align item to bottom of viewport |
'nearest' | Scroll to nearest edge if not visible |
'center' | Center the item vertically in the viewport, clamped at the list edges |
scrollToOffset()
Scroll to a raw pixel offset instead of an item index. Complements scroll() and is ideal for restoring a persisted scroll position after navigation.
Signature
scrollToOffset(options: {
offset: number
smoothScroll?: boolean
}): Promise<void>scrollToOffset(options: {
offset: number
smoothScroll?: boolean
}): Promise<void>The offset is clamped to the list’s valid scroll range, so values past the end settle at the bottom. The returned promise resolves once the scroll has visually finished.
Options
| Property | Type | Default | Description |
|---|---|---|---|
offset | number | required | Raw vertical scroll offset in pixels |
smoothScroll | boolean | true | Use smooth scroll animation |
Examples
Restore a saved scroll position instantly:
await listRef.scrollToOffset({ offset: 12345, smoothScroll: false })await listRef.scrollToOffset({ offset: 12345, smoothScroll: false })Smoothly scroll to a pixel offset:
await listRef.scrollToOffset({ offset: 2000 })await listRef.scrollToOffset({ offset: 2000 })scrollToTop()
Convenience method to scroll to the beginning.
await listRef.scrollToTop()await listRef.scrollToTop()scrollToBottom()
Convenience method to scroll to the end.
await listRef.scrollToBottom()await listRef.scrollToBottom()