Broad Infinite List ·

broad-infinite-list is a tiny component that renders large lists efficiently by showing only a limited range of items. No need to configure each row’s height or use fixed row heights. It is suitable for chat message lists, news feed lists, and stream logs.

Features

• 🔄 Bidirectional infinite scrolling
• ⚡ High performance - only renders fixed items
• 📏 Dynamic heights - no configuration needed
• 🪟 Window or container scrolling

Demos

React & Vue Demos

• Chat Messages List Demo
• News feed list & detail(Scroll Restoration when navigation back) Demo
• Logs Demo
• Vue Chat Demo
• ChatGPT Demo
• Claude theme Demo

Table of Contents

• Broad Infinite List ·
  • Features
  • Demos
    • React & Vue Demos
    • Expo Demo Preview(React Native)
  • How It Works
  • Installation
  • Quick Start
  • API
    • BidirectionalList Props
    • BidirectionalListRef
  • Development
  • FAQ
    • 1. What's the biggest advantage of this library?
    • 2. What's the difference between broad-infinite-list and react-window / TanStack/virtual / react-virtualized?
    • 3. Why should I use broad-infinite-list instead of others?
    • 4. What frameworks does broad-infinite-list support currently?
    • 5. What's the disadvantage of broad-infinite-list?
  • Projects You May Also Be Interested In
  • Reporting Issues
  • Support

Expo Demo Preview(React Native)

Note

Scan it, then open it in Expo Go.

How It Works

Define a fixed window of visible items (e.g., 30 entries from a 100,000-record dataset). Load items entering the viewport as the user scrolls, and remove items leaving the viewport. This keeps rendered items constant and maintains smooth performance with large datasets.

Installation

npm install broad-infinite-list

Quick Start

Caution

For vue3 or React Native usage, check the example in vue-example/src/App.vue or rn-expo-example/app/(tabs)/index.tsx

Note

For React web, copy and paste the below demo code, then run it.

"use client";
import { useState, useRef } from "react";
import BidirectionalList, {
  type BidirectionalListProps,
  type BidirectionalListRef,
} from "broad-infinite-list/react";

interface NewsItem {
  id: number;
  title: string;
  category: string;
  timestamp: number;
}

const CATEGORIES = ["Tech", "Science", "Politics", "Business"];
const TITLES = [
  "Senate Passes Landmark Infrastructure Bill",
  "New AI Model Achieves Human-Level Performance",
  "Global Temperatures Record Highest Monthly Average",
  "Startup Raises $200M Series C for Autonomous Systems",
];

const TOTAL = 1000000;
const ALL_NEWS: NewsItem[] = Array.from({ length: TOTAL }, (_, i) => ({
  id: i + 1,
  title: `${i + 1}. ${TITLES[i % TITLES.length] || ""}`,
  category: CATEGORIES[i % CATEGORIES.length] || "",
  timestamp: Date.now() - (TOTAL - i) * 3600000,
}));

const NEWS_BY_RECENCY = [...ALL_NEWS].reverse();

const VIEW_COUNT = 50;
const PAGE_SIZE = 20;

function MyList() {
  const [items, setItems] = useState<NewsItem[]>(
    NEWS_BY_RECENCY.slice(0, VIEW_COUNT)
  );

  const newestLoaded = items[0]?.id ?? 0;
  const oldestLoaded = items[items.length - 1]?.id ?? ALL_NEWS.length + 1;
  const hasPrevious = newestLoaded < ALL_NEWS.length;
  const hasNext = oldestLoaded > 1;

  const handleLoadMore: BidirectionalListProps<NewsItem>["onLoadMore"] = async (
    direction,
    refItem
  ) => {
    await new Promise((r) => setTimeout(r, 200));
    const idx = NEWS_BY_RECENCY.findIndex((n) => n.id === refItem.id);
    if (direction === "down") {
      return NEWS_BY_RECENCY.slice(idx + 1, idx + PAGE_SIZE + 1);
    } else {
      return NEWS_BY_RECENCY.slice(idx - PAGE_SIZE, idx);
    }
  };

  const listRef = useRef<BidirectionalListRef>(null);
  const showScrollTopButton = items?.[0]?.id !== NEWS_BY_RECENCY[0]?.id;
  const onScrollToFirst = () => {
    setItems(NEWS_BY_RECENCY.slice(0, VIEW_COUNT));
    listRef.current?.scrollToTop();
  };

  return (
    <>
      <BidirectionalList<NewsItem>
        ref={listRef}
        items={items}
        itemKey={(item) => item.id.toString()}
        spinnerRow={
          <div className="p-4 flex justify-center">
            <Spinner />
          </div>
        }
        renderItem={(item) => (
          <div
            style={{
              padding: 16 + item.id * 0.000035,
              borderBottom: "1px solid #ddd",
              backgroundColor: item.id % 2 === 0 ? "#eee" : "#f5f6f7",
            }}>
            <div style={{ fontWeight: 600 }}>{item.title}</div>
            <div style={{ fontSize: 12, color: "#666" }}>{item.category}</div>
          </div>
        )}
        onLoadMore={handleLoadMore}
        onItemsChange={setItems}
        hasPrevious={hasPrevious}
        hasNext={hasNext}
        viewCount={VIEW_COUNT}
        useWindow={true}
      />
      <button
        id="scrollToTopBtn"
        onClick={onScrollToFirst}
        className={
          "fixed bottom-5 right-5 bg-blue-600 text-white p-3 rounded-full shadow-lg hover:bg-blue-700 transition-opacity z-9 " +
          (showScrollTopButton
            ? "opacity-100"
            : "opacity-0 pointer-events-none")
        }>
        ↑
      </button>
      <div className="fixed z-9 top-5 p-2 text-xs right-5 rounded-xl shadow-lg bg-slate-200/55">
        <p>Total: {TOTAL}(1million)</p>
        <p>Display: {items.length}</p>
        <p>useWindow: {"true"}</p>
      </div>
    </>
  );
}

const Spinner = () => (
  <div className="size-6 border-2 border-slate-300 border-t-blue-400 rounded-full animate-spin" />
);

export default MyList;

API

BidirectionalList Props

Property	Type	Required	Default	Description
items	T[]	Yes	-	Current array of items to display
itemKey	(item: T) => string | number	Yes	-	Function to extract a unique key from each item
renderItem	(item: T) => React.ReactNode	Yes	-	Function to render each item
onLoadMore	(direction: "up" | "down", refItem: T) => Promise<T[]>	Yes	-	Called when more items should be loaded; returns the new items to prepend/append
hasPrevious	boolean	Yes	-	Whether there are more items available above the current view
hasNext	boolean	Yes	-	Whether there are more items available below the current view
onItemsChange	(items: T[]) => void	No	undefined	Called when the items array changes due to loading or trimming
className	string	No	undefined	The container tag's className
itemClassName	string | (items: T, index: number) => string	No	undefined	The item tag's className
itemStyle	itemStyle?: CSSProperties | ((item: T, index: number) => CSSProperties | undefined);	No	undefined	The item element's style
listClassName	string	No	undefined	The list wrapper div's className
containerAs	string	No	div	The container tag, default is div, example: conatinerAs='table'
as	string	No	div	The list wrapper tag, default is div, example: as='ul'
itemAs	string	No	div	The item tag, default is div, example: itemAs='li'
spinnerRow	React.ReactNode	No	undefined	Custom loading indicator shown during fetch
emptyState	React.ReactNode	No	undefined	Content to display when items array is empty
viewCount	number	No	50	Maximum number of items to keep in DOM; older items are trimmed
threshold	number	No	10	Pixel distance from edge to trigger loading
useWindow	boolean	No	false	If true, use window scroll instead of container scroll
disable	boolean	No	false	If true, disable loading in both directions
onScrollStart	() => void	No	undefined	Called when a programmatic scroll adjustment begins
onScrollEnd	() => void	No	undefined	Called when a programmatic scroll adjustment ends
headerSlot	({children}: {children: ReactNode}) => children	No	undefined	for table element
footerSlot	({children}: {children: ReactNode}) => children	No	undefined	for table element
upOffset	number	No	undefined	Sticky header offset

BidirectionalListRef

Property	Type	Required	Default	Description
scrollViewRef	RefObject<HTMLElement | null>	Yes	-	Reference to the scrollable container element
scrollToTop	(behavior?: ScrollBehavior) => void	Yes	-	Scroll to the top of the list
scrollToBottom	(behavior?: ScrollBehavior) => void	Yes	-	Scroll to the bottom of the list
scrollTo	(top: number, behavior?: ScrollBehavior) => void	Yes	-	Scroll to a specific pixel offset from top
scrollToKey	(key: string | number, behavior?: ScrollBehavior) => void	Yes	-	Scroll to an item by its key
getTopDistance	() => number	Yes	-	Get current distance to top
getBottomDistance	() => number	Yes	-	Get Current distance to bottom
handleLoad	(direction: 'up' | 'down', getItems: () => T[] | Promise<T[]>) => void	Yes	-	Manual Load Items (Previous, only support user scroll trigger load)

Development

This project use bun, but in rn-expo-example/ use pnpm.

bun install && bun run build

FAQ

1. What's the biggest advantage of this library?

The idea for broad-infinite-list is pretty straightforward: an infinite scroll list ➕ a fixed number of items rendered ➕ avoiding layout shifts after items are trimmed. That’s why it’s only 2 KB gzipped. No magic, no complicated theory.

2. What's the difference between broad-infinite-list and react-window / TanStack/virtual / react-virtualized?

Those three libraries (react-window, TanStack/virtual, and react-virtualized) are similar, and their demos require a fixed height for each item. broad-infinite-list is a bidirectional infinite scroll list component that only renders a fixed number of items. It's not complicated. Naturally support dynamic height items.

3. Why should I use broad-infinite-list instead of others?

There are three main reasons why you should use broad-infinite-list:

• 1. High performance: Bidirectional infinite scroll list.
• 2. Flexible: Supports the window or a custom div as the container.
• 3. Tiny: Only 2KB gzipped.

broad-infinite-list is quite new, but because of its simple implementation, means it has fewer bugs.

4. What frameworks does broad-infinite-list support currently?

Currently, broad-infinite-list supports React, React Native, and Vue.

5. What's the disadvantage of broad-infinite-list?

If you find any issues or disadvantages, please create an issue. I will review it and fix it if possible. Thank you.

Projects You May Also Be Interested In

• xior - The best tiny fetch library with axios-like API and built-in support rich plugins(Cache, Error retries, Requests throttle...)
• tsdk - Type-safe API development CLI tool for TypeScript projects v1.0.0 is coming 🚚
• useNextTick - nextTick but for react: Running callbacks after the DOM or native views have updated.

Reporting Issues

Found an issue? Please feel free to create issue

Support

If you find this project helpful, consider buying me a coffee.