@scrollstackjs/svelte

Svelte adapter for ScrollStack — a headless store plus a sentinel action. You bring the markup; the engine owns the behavior. 0.25 KB gzipped, and no Svelte runtime is imported, so it works in Svelte 4 and 5 alike.

📖 Docs · API reference · Live demo · Tutorial

npm i @scrollstackjs/svelte

Requires Svelte >= 4. Pulls in @scrollstackjs/core automatically.

Quick start

<script lang="ts">
  import { onDestroy } from 'svelte';
  import { createInfiniteScroll } from '@scrollstackjs/svelte';

  const scroll = createInfiniteScroll({
    initialPageParam: 0,
    fetchPage: async ({ pageParam, signal }) =>
      (await fetch(`/api/items?cursor=${pageParam}`, { signal })).json(),
    getNextPageParam: (last) => last.nextCursor, // null = no more pages
  });
  const { target } = scroll;
  onDestroy(scroll.destroy);
</script>

<ul>
  {#each $scroll.pages.flatMap((p) => p.items) as item (item.id)}<li>{item.name}</li>{/each}
  {#if $scroll.hasNextPage}<li use:target>{$scroll.isFetchingNextPage ? 'Loading…' : ''}</li>{/if}
</ul>

The returned value is a Svelte store, so $scroll is the core snapshot. The use:target sentinel loads the next page when it scrolls into view. The store also carries loadNextPage, retry, reset, destroy and engine.

Handling errors

A failed load-more keeps the pages you already have — status stays 'success' while error is set, so you can offer a retry without blanking the list:

{#if $scroll.error && $scroll.pages.length && !$scroll.isFetching}
  <button on:click={scroll.retry}>Retry</button>
{/if}

Learn more

| | | | ------------------------------------------------------------------- | ------------------------------------------- | | Getting started | Install and first feed | | Core concepts | The snapshot and the two-axis state machine | | Pagination | Cursor, offset and page-number recipes | | Errors & retry | Backoff, manual retry, load-more failures | | Server rendering | SvelteKit and what runs where | | Devtools | Inspect the engine while you build |

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md.

MIT © devgauravjatt