# Scroll Methods
> Programmatically scroll to any item in the virtual list with configurable alignment options.
**Source:** [https://virtuallist.svelte.page/docs/scroll-methods](https://virtuallist.svelte.page/docs/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
> Live example: [/examples/scroll-to-item](https://virtuallist.svelte.page/examples/scroll-to-item)
## Basic Usage
To use the scroll method, bind a reference to the VirtualList component:
```svelte
{#snippet renderItem(item)}
{item.text}
{/snippet}
```
## API Reference
### scroll(options)
Scrolls the list to bring a specific item into view.
```typescript
scroll(options: {
index: number
smoothScroll?: boolean
shouldThrowOnBounds?: boolean
align?: 'auto' | 'top' | 'bottom' | 'nearest' | 'center'
}): Promise
```
### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `index` | `number` | Required | The item index to scroll to (0-based) |
| `smoothScroll` | `boolean` | `true` | Use smooth scrolling animation |
| `shouldThrowOnBounds` | `boolean` | `true` | Throw error if index is out of bounds |
| `align` | `string` | `'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' })`).
- **`'center'`** - Center the item vertically in the viewport, clamped at the list edges. Great for focusing a search result or highlighted item so it lands in the middle of the view.
## Examples
### Scroll to specific index
```svelte
```
### Scroll without animation
```svelte
```
### Always align to top
```svelte
```
### Minimal scrolling
```svelte
```
### Center the item in the viewport
```svelte
```
## scrollToOffset(options)
Scrolls the viewport to a raw pixel offset instead of an item index. This complements `scroll()` (which is index-based) and is ideal for restoring a persisted scroll position after navigation.
```typescript
scrollToOffset(options: {
offset: number
smoothScroll?: boolean
}): Promise
```
The offset is clamped to the list's valid scroll range, so values beyond the end simply settle at the bottom. The returned promise resolves once scrolling has visually finished.
### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `offset` | `number` | Required | Raw vertical scroll offset in pixels |
| `smoothScroll` | `boolean` | `true` | Use smooth scrolling animation |
### Example
```svelte
{#snippet renderItem(item)}
{item.text}
{/snippet}
```
## TypeScript
For full type safety, you can type the ref:
```typescript
type ListRef = {
scroll: (options: {
index: number
smoothScroll?: boolean
shouldThrowOnBounds?: boolean
align?: 'auto' | 'top' | 'bottom' | 'nearest' | 'center'
}) => Promise
scrollToOffset: (options: {
offset: number
smoothScroll?: boolean
}) => Promise
}
let listRef: ListRef | undefined = $state(undefined)
```
Or import the types from the package:
```typescript
import type {
SvelteVirtualListScrollOptions,
SvelteVirtualListScrollAlign
} from '@humanspeak/svelte-virtual-list'
```