svelte-tiny-virtual-list

You can install the library using npm, yarn, or pnpm:

$ npm install svelte-tiny-virtual-list

$ yarn add svelte-tiny-virtual-list

$ pnpm install svelte-tiny-virtual-list

The itemSize prop is highly flexible and can be provided in three ways:

1. Fixed Size: A single number if all items are identical.
2. Array of Sizes: A number[] where each element corresponds to the size of the item at that index.
3. Getter Function: A function (index: number) => number for dynamic or calculated sizes.

// Fixed
itemSize={50}

// Array
itemSize={[50, 100, 50, 75]}

// Function
itemSize={(index) => index % 2 === 0 ? 50 : 100}

The svelte-tiny-virtual-list package exports the main VirtualList.svelte component as the default export. You can import it directly from the package to use it in your Svelte applications.

<script>
  import VirtualList from 'svelte-tiny-virtual-list';
</script>

Instead of traditional slots, svelte-tiny-virtual-list uses Svelte Snippets for rendering content.

item Snippet

This is the primary snippet used to render each list item. It receives an object containing:

• index: number - The index of the item.
• style: string - The calculated style (e.g., position, transform) that must be applied to the item's container element.

header and footer Snippets

• header: An optional snippet rendered above the list.
• footer: An optional snippet rendered below the list.

Note: The children slot is deprecated in favor of the item snippet.

<VirtualList 
  {itemCount} 
  {itemSize} 
  height={500}
>
  {#snippet item({ index, style })}
    <div style={style}>
      Item {index}
    </div>
  {/snippet}
</VirtualList>

The component emits two main events to allow synchronization with external state or logic:

onItemsUpdated

Called whenever the range of visible items changes. It provides a detail object:

• start: number - Index of the first visible item.
• end: number - Index of the last visible item.

onAfterScroll

Called after the scroll event has been handled. It provides a detail object:

• event: Event - The original scroll event.
• offset: number - The current value of wrapper.scrollTop or wrapper.scrollLeft.

The DIRECTION constant defines the orientation of the virtual list. This affects how scrolling and alignment are handled.

• HORIZONTAL: For lists scrolling left-to-right.
• VERTICAL: For lists scrolling top-to-bottom.

import { DIRECTION } from 'svelte-tiny-virtual-list';

// Example usage in a component prop
<VirtualList direction={DIRECTION.HORIZONTAL} ... />

When configuring the alignment of items within the virtual list, use the ALIGNMENT constant to ensure type safety and avoid string typos. Supported values are:

• AUTO: Automatic alignment.
• START: Align to the start of the container.
• CENTER: Align to the center.
• END: Align to the end of the container.

import { ALIGNMENT } from 'svelte-tiny-virtual-list';

// Example usage in a component prop
<VirtualList alignment={ALIGNMENT.CENTER} ... />

The package exports several types for configuring the component and handling events. Use these for type-safe implementations in TypeScript.

import type {
	AfterScrollDetail,
	Alignment,
	Direction,
	ItemSize,
	ItemsUpdatedDetail,
	ScrollBehaviour,
	VirtualListEvents,
	VirtualListProps,
	VirtualListSnippets
} from 'svelte-tiny-virtual-list';