Infinite Scroll
Doomscrolling, now as a component. Loads more content as you scroll near an edge, in any of four directions.
Installation
Comes with the scroll area.
Usage
<script setup lang="ts">
import { InfiniteScroll, ScrollArea } from '@/components/ui/scroll-area'
const load = async ({ index }: { index: number }) => {
const page = await fetchPage(index)
items.value = [...items.value, ...page.items]
if (page.last) return 'stop'
}
</script>
<template>
<ScrollArea class="h-72">
<InfiniteScroll :on-load="load">
<p v-for="item in items" :key="item.id">{{ item.text }}</p>
</InfiniteScroll>
</ScrollArea>
</template>
Scroll within offset pixels of the edge, and onLoad gets called with { direction, index }. index starts at 1, so it doubles as a page number. It won't fire again until the promise settles.
Out of content? Return 'stop'. To start again, call resume() or reset().
If the promise throws, the next scroll retries the same page, and the error goes to app.config.errorHandler.
Examples
Reverse
directions="['top']" loads older content at the top, like a chat. Your reading position stays put while new content appears above.
Scroll the area to the bottom before turning loading on, or it hits the top edge right on mount.
Horizontal
start and end load sideways. In right-to-left pages, they flip.
Both directions
Each direction lives its own life: its own page count, loading state and stop. One loading doesn't block the other.
The composable
useInfiniteScroll() is the same thing without markup, for lists that draw their own loading rows. It returns the same things InfiniteScroll exposes.
const rootRef = useTemplateRef<HTMLElement>('root')
const { state, reset } = useInfiniteScroll({
anchor: rootRef,
directions: ['bottom'],
onLoad: async ({ index }) => {
/* … */
},
})
target: what to watch, an element,windowor aScrollAreaAPI. By default, the nearest scrolling parent ofanchor, or the window. With a virtualizedScrollAreaset toanchorTo: 'end', pass its API: the anchor then holds the rows loaded at the top in place, and the composable doesn't shift them a second time.shouldLoad(direction): your own "time to load?" check instead of the pixel offset. Handy for virtualized lists that count rows.InfiniteScrolltakes it as a prop too.
API Reference
InfiniteScroll
class is also accepted, for the root.
| Prop | Default | Type and description |
|---|---|---|
| onLoad* | — | InfiniteScrollLoadCalled with |
| target | null | InfiniteScrollTarget | nullWhat scrolls. An element, the |
| directions | ["bottom"] | InfiniteDirection[]The edges to load from. |
| offset | 200 | numberDistance in pixels from an edge at which a load starts. 200 by default. |
| debounce | 100 | numberMilliseconds between checks while scrolling. 100 by default; 0 checks on every scroll event. |
| initialFill | true | booleanAfter each load, load again while the content does not fill the viewport. On by default. |
| disabled | false | booleanStops loading. Turning it off checks the edges at once. |
| resetKey | — | unknownAny value; when it changes, every direction resets to index 0 and starts over. |
| shouldLoad | — | ((direction: InfiniteDirection) => boolean | undefined)Your own "time to load?" check for an edge, called with its direction in place of the |
| Slot | Scope and description |
|---|---|
| default | anyThe content. |
| loading | { direction: InfiniteDirection; }What shows at an edge while it loads; a |
| end | { direction: InfiniteDirection; }What shows at an edge once it is stopped. Receives |
| Member | Type and description |
|---|---|
| state | Readonly<Ref<Record<InfiniteDirection, InfiniteScrollState>, Record<InfiniteDirection, InfiniteScrollState>>>The |
| trigger | (direction?: InfiniteDirection | undefined) => voidLoads a direction now, unless it is loading, stopped or disabled. The first listed direction by default. |
| stop | (direction?: InfiniteDirection | undefined) => voidStops a direction, or all of them. |
| resume | (direction?: InfiniteDirection | undefined) => voidStarts a stopped direction again, or all of them, and checks the edges. |
| reset | (direction?: InfiniteDirection | undefined) => voidSets a direction, or all of them, back to index 0 and not stopped, then checks the edges. |
| setIndex | (direction: InfiniteDirection, index: number) => voidSets the next load index of a direction. |
| poll | () => voidChecks the edges now, after content changed without a scroll. |
| getTarget | () => ScrollTarget | nullThe resolved scroll target. |
class is also accepted, for the root.
Props
- onLoad*
InfiniteScrollLoadCalled with{ direction, index }when an edge is near.indexcounts loads in that direction from 1. Resolve to load again later, resolve'stop'when that direction has no more; a rejection rolls the index back and reports the error.- target
null InfiniteScrollTarget | nullWhat scrolls. An element, thewindow, or aScrollAreaAPI. Left out, the surroundingScrollArea's viewport, else the nearest scrolling ancestor, else the window.- directions
["bottom"] InfiniteDirection[]The edges to load from.top,bottom,startandend;startandendare logical.['bottom']by default.- offset
200 numberDistance in pixels from an edge at which a load starts. 200 by default.- debounce
100 numberMilliseconds between checks while scrolling. 100 by default; 0 checks on every scroll event.- initialFill
true booleanAfter each load, load again while the content does not fill the viewport. On by default.- disabled
false booleanStops loading. Turning it off checks the edges at once.- resetKey
unknownAny value; when it changes, every direction resets to index 0 and starts over.- shouldLoad
((direction: InfiniteDirection) => boolean | undefined)Your own "time to load?" check for an edge, called with its direction in place of theoffsetcheck. Returnundefinedto fall back tooffset.
Slots
- default
anyThe content.- loading
{ direction: InfiniteDirection; }What shows at an edge while it loads; aSpinnerby default. Receives{ direction }.- end
{ direction: InfiniteDirection; }What shows at an edge once it is stopped. Receives{ direction }.
Exposed
- state
Readonly<Ref<Record<InfiniteDirection, InfiniteScrollState>, Record<InfiniteDirection, InfiniteScrollState>>>The{ index, loading, stopped }of each direction.- trigger
(direction?: InfiniteDirection | undefined) => voidLoads a direction now, unless it is loading, stopped or disabled. The first listed direction by default.- stop
(direction?: InfiniteDirection | undefined) => voidStops a direction, or all of them.- resume
(direction?: InfiniteDirection | undefined) => voidStarts a stopped direction again, or all of them, and checks the edges.- reset
(direction?: InfiniteDirection | undefined) => voidSets a direction, or all of them, back to index 0 and not stopped, then checks the edges.- setIndex
(direction: InfiniteDirection, index: number) => voidSets the next load index of a direction.- poll
() => voidChecks the edges now, after content changed without a scroll.- getTarget
() => ScrollTarget | nullThe resolved scroll target.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| infinite-scroll | data-orientation, aria-busy | The root. A flex row when a horizontal direction is listed. |
| infinite-scroll-loading | data-direction, data-state | The loading part at one edge, present until that direction stops. Invisible but keeping its room while idle. |
| infinite-scroll-end | data-direction | The end slot at one edge, rendered once that direction is stopped and the slot is given. |
Accessibility
The root gets aria-busy while loading. Loading indicators are hidden from screen readers, so if new content matters to your users, announce it yourself.