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.
- 🔄 Bidirectional infinite scrolling
- ⚡ High performance - only renders fixed items
- 📏 Dynamic heights - no configuration needed
- 🪟 Window or container scrolling
- Chat Messages List Demo
- News feed list & detail(Scroll Restoration when navigation back) Demo
- Logs Demo
- Vue Chat Demo
- ChatGPT Demo
- Claude theme Demo
[!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.
npm install broad-infinite-list
[!CAUTION] For vue3 or React Native usage, check the example in
vue-example/src/App.vueorrn-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;
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
items |
T[] |
Yes | - | Current array of items to display |
itemKey |
(item: T) => string |
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 |
| 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, 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 |
This project use bun, but in rn-expo-example/ use pnpm.
bun install && bun run build
Found an issue? Please feel free to create issue
If you find this project helpful, consider buying me a coffee.
- xior - Tiny fetch library with plugins support and axios-like API
- tsdk - Type-safe API development CLI tool for TypeScript projects
- useNextTick -
nextTickbut for react: Running callbacks after the DOM or native views have updated.