@scrollstackjs/vue

Vue 3 adapter for ScrollStack — a headless useInfiniteScroll composable. You bring the markup; the engine owns the behavior. 0.29 KB gzipped, with teardown wired to the effect scope so it cleans up on unmount.

📖 Docs · API reference · Live demo · Tutorial

npm i @scrollstackjs/vue

Requires Vue >= 3.3. Pulls in @scrollstackjs/core automatically.

Quick start

<script setup lang="ts">
import { useInfiniteScroll } from '@scrollstackjs/vue';

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

<template>
  <ul>
    <li v-for="item in state.pages.flatMap((p) => p.items)" :key="item.id">{{ item.name }}</li>
    <li v-if="state.hasNextPage" :ref="target">{{ state.isFetchingNextPage ? 'Loading…' : '' }}</li>
  </ul>
</template>

The target sentinel loads the next page when it scrolls into view. state is a shallowRef of the core snapshot — auto-unwrapped in templates, state.value in <script setup>. Also returned: loadNextPage, retry, reset, 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:

<button v-if="state.error && state.pages.length && !state.isFetching" @click="retry">
  Retry
</button>

Why :ref="target" and not ref="target"? Vue invokes function refs on every patch, so the adapter dedupes on the observed node — otherwise each re-render would attach a fresh observer and trigger a refetch loop. Bind it as a dynamic ref.

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 | What runs where | | Devtools | Inspect the engine while you build |

Contributing

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

MIT © devgauravjatt