react-virtualised-scroll
v1.1.0TypeScript
High-performance virtualized scroll component for React
reactreact-componentvirtual-scrollwindowinginfinite-scrollasync-scrolllazy-loadingperformancelarge-listslist-virtualization
0/weekUpdated 1 months agoMITUnpacked: 71.3 KB
Published by exec
npm install react-virtualised-scrollreact-virtualised-scroll
A small, high-performance virtualized scroll React component with async loading. It fetches only the visible slice of items (plus a small buffer), measures the item height automatically and provides simple sticky loading indicators for top/bottom fetches.
Features
* Virtualizes large lists to reduce DOM nodes
* Skeleton support
* Multiply layouts support
* Totally aggresive optimization having large dataset due to virtualization
Install
``
bash
npm install react-virtualised-scroll
or
yarn add react-virtualised-scroll
`
Types
`ts
export interface VirtualScrollDataLayout> {
comp: ForwardRefExoticComponent>; // user component
skeleton: React.ComponentType<{ style?: React.CSSProperties }>; // user skeleton
elemsCount: number; // count of elements in torrent, this need for calculating height or width(for VirtualScrollRow) of container. For VirtualScrollRow this is not number of rows as well.
// needs for measurement the height for container
boundNode: ReactNode;
}
export interface TorrentData {
lKey: string;
data: T;
};
export interface VirtualScrollBaseProps {
wrapperClasses?: string;
wrapperStyle?: CSSProperties;
containerClasses?: string;
containerStyle?: CSSProperties;
innerContainerClasses?: string;
innerContainerStyle?: CSSProperties;
}
export interface VirtualScrollProps<
T extends Record
> extends VirtualScrollBaseProps {
// fetch callback
torrent: (offset: number, size: number) => Promise[]>;
// elemCount: number;
layout: { [key: string]: VirtualScrollDataLayout };
// custom batch of items per render
pageSize?: number;
additionalHeight?: number;
overrideHeight?: number;
// use this when there's no known count of elements
// progressive height
isInfinite?: boolean;
// cache config
useCache?: boolean;
cacheSize?: number;
}
export interface VirtualScrollRowProps> extends VirtualScrollBaseProps {
torrent: (offset: number, size: number) => Promise[]>;
layout: { key: string, layout: VirtualScrollDataLayout }; // User's default component that is in a row.
rowLayout?: { [key: string]: VirtualScrollDataLayout }; // Custom row layouts
pageSize?: number;
additionalHeight?: number;
overrideHeight?: number;
isInfinite?: boolean;
gapX?: number;
// NOTE: gapY is not just gap, it's paddingBottom of the internal row
gapY?: number;
useCache?: boolean;
cacheSize?: number;
}
`
Notes:
* The parent container must have a fixed height (or constrained height) so the internal container can set overflow and measure scroll offset. In many layouts this is the element that wraps VirtualScroll.
* The item component should have a fixed height for best measurement. The component measures the first rendered item via ref to determine relemHeight.
Example using single layout
`tsx
import React from 'react';
import { VirtualScroll, VirtualScrollDataLayout, TorrentData } from 'react-virtualised-scroll';
// 1. Define your data type
interface MessageItem {
id: number;
sender: string;
message: string;
timestamp: string;
avatar: string;
}
// 2. Main component (MUST use forwardRef)
const MessageComponent = React.forwardRef(
({ sender, message, timestamp, avatar }, ref) => {
return (
ref={ref}
style={{
padding: '12px 16px',
borderBottom: '1px solid #eee',
display: 'flex',
gap: '12px',
}}
>
![]()
src={avatar}
alt={sender}
style={{ width: 40, height: 40, borderRadius: '50%' }}
/>
{sender}
{message}
{timestamp}
);
}
);
MessageComponent.displayName = 'MessageComponent';
// 3. Skeleton loader (matches component height)
const MessageSkeleton = ({ style }: { style?: React.CSSProperties }) => (
style={{
...style,
padding: '12px 16px',
borderBottom: '1px solid #eee',
display: 'flex',
gap: '12px',
}}
>
);
// 4. Generate mock data
const mockMessages = Array.from({ length: 10000 }, (_, i) => ({
id: i,
sender: User ${i + 1}
,
message: This is message number ${i + 1}. Lorem ipsum dolor sit amet.,
timestamp: new Date(Date.now() - i * 60000).toLocaleTimeString(),
avatar: https://i.pravatar.cc/40?u=${i},
}));
// 5. Setup layout configuration
const messageLayout: { [key: string]: VirtualScrollDataLayout } = {
message: {
comp: MessageComponent,
skeleton: MessageSkeleton,
elemsCount: 10000, // Total expected items
boundNode: (
sender="Sample User"
message="Sample message for measurement"
timestamp="12:00 PM"
avatar="https://via.placeholder.com/40"
ref={null as any} // Measurement only, ref not needed
/>
),
},
};
// 6. Implement torrent function (simulates API)
const torrent = async (
offset: number,
size: number
): Promise[]> => {
await new Promise((resolve) => setTimeout(resolve, 450)); // Simulate network delay
return mockMessages.slice(offset, offset + size).map((item) => ({
lKey: 'message',
data: item,
}));
};
export const MessageList = () => {
return (
torrent={torrent}
layout={messageLayout}
pageSize={30} // Load 30 items per batch
cacheSize={300} // Keep last 300 items in memory
useCache={true}
isInfinite={false} // we have known items count so we don't use this
/>
);
};
export default function App() {
return (
);
}
`
Example using multiply layouts
`tsx
import React, {
forwardRef,
useCallback,
useMemo
} from "react";
import {
TorrentData,
VirtualScroll
} from "react-virtualised-scroll";
interface BaseData { id: number; timestamp: string; }
interface CardData extends BaseData { title: string; imageUrl: string; likes: number; }
interface ListData extends BaseData { name: string; description: string; status: "online" | "offline" | "busy"; }
interface DetailData extends BaseData { author: string; content: string; tags: string[]; }
interface CompactData extends BaseData { event: string; priority: "low" | "medium" | "high"; }
// ==================== LAYOUT 1: CARD COMPONENT (150px) ====================
const CardComponent = forwardRef((props, ref) => {
return (
ref= { ref }
style = {{
height: "150px",
display: "flex",
border: "1px solid #e0e0e0",
borderRadius: "8px",
overflow: "hidden",
background: "white",
boxShadow: "0 2px 4px rgba(0,0,0,0.1)",
}
}
>
< div style = {{ padding: "16px", flex: 1, display: "flex", flexDirection: "column" }}>
{ props.title }
< p style = {{ margin: "auto 0 8px 0", color: "#666", fontSize: "14px" }}>
ID: { props.id } • { props.timestamp }
< div style = {{ display: "flex", alignItems: "center", gap: "16px" }}>
♥ { props.likes }
< button
style = {{
marginLeft: "auto",
padding: "6px 12px",
background: "#1976d2",
color: "white",
border: "none",
borderRadius: "4px",
cursor: "pointer",
}}
>
View Details
);
});
const CardSkeleton = ({ style }: { style?: CSSProperties }) => (
style= {{
...style,
height: "150px",
display: "flex",
border: "1px solid #e0e0e0",
borderRadius: "8px",
background: "linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%)",
backgroundSize: "200% 100%",
animation: "loading 1.5s infinite",
}}
>
< div style = {{ padding: "16px", flex: 1 }}>
< div style = {{ height: "14px", width: "80%", background: "#e0e0e0", marginBottom: "8px" }} />
< div style = {{ height: "14px", width: "50%", background: "#e0e0e0", marginBottom: "16px" }} />
< div style = {{ height: "32px", width: "100px", background: "#e0e0e0", marginLeft: "auto" }} />