wc-infinite-scroller

A native Web Component implementation of an infinite scroller with page-based data fetching, LRU caching, and virtual placeholder support.

Installation

npm install wc-infinite-scroller

Usage

As an ES module (recommended)

import { register } from 'wc-infinite-scroller'

register() // registers <infinite-scroller> custom element

Side-effect import (auto-registers on load)

import 'wc-infinite-scroller'

Via <script> tag (UMD)

<script src="node_modules/wc-infinite-scroller/dist/infinite-scroller.umd.cjs"></script>

HTML

<infinite-scroller id="scroller"></infinite-scroller>

JavaScript

const scroller = document.getElementById('scroller')

scroller.fetchPage = async (page) => {
  const res = await fetch(`/api/items?page=${page}`)
  const data = await res.json()
  return {
    items: data.items,
    currentPage: page,
    totalPages: data.totalPages,
  }
}

scroller.renderItem = (item) => {
  const el = document.createElement('div')
  el.textContent = item.name
  return el
}

scroller.loadInitialPage()

Custom element template

You can provide your own container element instead of the default <ul> list by placing HTML inside the component. The first child element will be used as the scroll container:

<infinite-scroller id="scroller">
  <div class="my-list"></div>
</infinite-scroller>

API

Properties

| Property | Type | Description | | --------------------------- | -------------------------------------------------- | ------------------------------------------------------------------ | | fetchPage | (page: number) => Promise<PageResult<T>> | Required. Called to fetch a page of data. | | renderItem | (item: T) => HTMLElement \| Promise<HTMLElement> | Required. Called to render each data item. | | currentPage | number | Gets or sets the current page (triggers load). | | createPageElement | () => HTMLElement | Optional. Factory for the wrapper element of each page. | | createPlaceholderElements | () => HTMLElement[] | Optional. Factory for placeholder elements shown while loading. | | createErrorElement | (estimatedHeight: number) => HTMLElement | Optional. Factory for the element shown when a page fails to load. |

Methods

| Method | Description | | ------------------- | ----------------------------------------- | | loadInitialPage() | Loads the initial page. Call after setup. |

Attributes

| Attribute | Default | Description | | --------------- | -------------------- | --------------------------------------------------- | | current-page | 1 | Initial page to load. | | preload-pages | 2 | Number of pages to preload around the current page. | | cache-size | preload-pages * 10 | Minimum LRU cache size. |

Events

| Event | Detail | Description | | ---------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | page-changed | { page: number, previousPage: number } | Fired when the visible page changes during scrolling. | | pages-fetched | { pages: { pageNum: number, pageResult: PageResult<T> \| null }[], mainPage: number } | Fired after a batch of pages is fetched. | | item-element-removed | Element | Fired when a rendered item element is removed from the DOM. |

TypeScript

Types are bundled. The InfiniteScroller class is generic:

import {
  InfiniteScroller,
  register,
  type PageResult,
  type PageChangedEvent,
  type PagesFetchedEvent,
  type ItemElementRemovedEvent,
} from 'wc-infinite-scroller'

interface MyItem {
  id: number
  name: string
}

const scroller = document.querySelector(
  'infinite-scroller'
) as InfiniteScroller<MyItem>

scroller.addEventListener('pages-fetched', (e) => {
  const event = e as PagesFetchedEvent<MyItem>
  console.log('fetched pages', event.detail?.pages)
})

License

MIT