Virtualized List and Grid Component

This project provides virtualized list and grid components for efficient rendering of large datasets.

It provides the following components:

• FixedList: A list component that renders items of a fixed height/width.
• DynamicList: A list component that renders items of varying heights/widths.
• VirtualizedGrid: A grid component that renders a large number of rows and columns efficiently.

Contents

• Virtualized List and Grid Component
  • FixedList
    • FixedListProps
    • FixedList - Usage
  • DynamicList
    • DynamicListProps
    • DynamicList - Usage
  • VirtualizedGrid
    • VirtualizedGridProps
    • VirtualizedGrid - Usage

FixedList

FixedListProps

Prop	Type	Default	Description	Required
children	JSX.Element[]	-	The children to render in the list	✓
totalElements	number	-	The total number of elements in the list	✓
width	number	"100%"	The width of the container
height	number	"100%"	The height of the container
overscanCount	number	3	The number of elements to render outside of the visible area
gap	number	0	The gap between each item in the list
itemSize	number	-	The size of each item in the list
orientation	"vertical" | "horizontal	"vertical"	The orientation of the list
reverse	boolean	false	Indicates if the list should start at the bottom

FixedList - Usage

The FixedList component is used to render a list of items where each item has a fixed height/width. It can be an horizontal or vertical list. The itemSize prop is required when using the FixedList component. The itemSize prop specifies the height or width (depending on the orientation) of each item in the list.

1import { FixedList } from "virtualize-it";
2import { ChildComponentProps } from "./types";
3
4function ChildComponent(props: ChildComponentProps) {
5  return (
6    <div
7      style={{
8        height: "100px",
9        width: "100%",
10      }}
11    >
12      <h1>{props.title}</h1>
13      <p>{props.description}</p>
14    </div>
15  );
16}
17
18function MainComponent() {
19  return (
20    <div className='w-full h-full'>
21      <FixedList
22        totalElements={100}
23        itemSize={100}
24        overscanCount={3}
25        gap={10}
26        orientation='vertical'
27      >
28        {Array.from({ length: 100 }).map((item, index) => (
29          <ChildComponent
30            key={item.id} // IMPORTANT: use a consistent key for each item, don't use the index.
31            title={`Title ${index}`}
32            description={`Description ${index}`}
33          />
34        ))}
35      </FixedList>
36    </div>
37  );
38}

DynamicListProps

DynamicListProps

Prop	Type	Default	Description	Required
children	JSX.Element[]	-	The children to render in the list	✓
totalElements	number	-	The total number of elements in the list	✓
getItemSize	function	-	A function that returns the size of each item	✓
width	number	"100%"	The width of the container
height	number	"100%"	The height of the container
overscanCount	number	3	The number of elements to render outside of the visible area
gap	number	0	The gap between each item in the list
orientation	string	"vertical"	The orientation of the list
reverse	boolean	false	Indicates if the list should start at the bottom

DynamicList - Usage

The DynamicList component is used to render a list of items where each item has a varying height/width. It can be an horizontal or vertical list. It is thinked to be used in list where the items have different heights/widths based on the type or content of the item. The getItemSize prop is required when using the DynamicList component. It is a function that receives the index of the item as an argument and returns the height or width (depending on the orientation) of each item in the list.

1import { DynamicList } from "virtualize-it";
2import { useCallback } from "react";
3
4const data = [
5  {
6    id: 1,
7    type: "text",
8    content: "This is a text item",
9  },
10  {
11    id: 2,
12    type: "image",
13    content: "https://example.com/image.jpg",
14  },
15  {
16    id: 3,
17    type: "text",
18    content: "This is another text item",
19  },
20];
21
22const sizeMap = {
23  text: 100,
24  image: 200,
25};
26
27function ChildComponent(props) {
28  return (
29    <div
30      style={{
31        height: "100px",
32        width: "100%",
33      }}
34    >
35      {props.type === "image" && <img src={props.content} alt='image' />}
36
37      {props.type === "text" && <h1>{props.content}</h1>}
38    </div>
39  );
40}
41
42function MainComponent() {
43  const getItemSize = useCallback((index: number) => {
44    // NOTE: consider memoizing this function if it will not change frequently.
45    const item = data[index];
46
47    return sizeMap[item.type];
48  }, []);
49
50  return (
51    <div className='w-full h-full'>
52      <DynamicList
53        totalElements={data.length}
54        getItemSize={getItemSize}
55        overscanCount={1}
56        gap={10}
57      >
58        {data.map((item, index) => (
59          <ChildComponent
60            key={item.id} // IMPORTANT: use a consistent key for each item, don't use the index.
61            type={item.type}
62            content={item.content}
63          />
64        ))}
65      </DynamicList>
66    </div>
67  );
68}

VirtualizedGrid

VirtualizedGridProps

Prop	Type	Default	Description	Required
rowHeight	number	-	The height of each row in the grid	✓
columnWidth	number	-	The width of each column in the grid
totalRows	number	-	The total number of rows in the grid	✓
totalColumns	number	-	The total number of columns in the grid
width	number	"100%"	The width of the container
height	number	"100%"	The height of the container
rowOverscanCount	number	3	The number of rows to render outside of the visible area
columnOverscanCount	number	3	The number of columns to render outside of the visible area
rowGap	number	0	The gap between each row in the grid
columnGap	number	0	The gap between each column in the grid

VirtualizedGrid - Usage

The VirtualizedGrid component is used to render a grid of items where each item has a fixed height/width. The children of the VirtualizedGrid component should be a 2D array where each element in the outer array represents a row and each element in the inner array represents a column.

If the totalColumns or columnWidth props are not provided the component will behave as a FixedList. Also if the children of each row element are not an array the component will behave as a FixedList.

1import { VirtualizedGrid } from "virtualize-it";
2
3const data = Array.from({ length: 1000 }).map((_, index) => ({
4  id: index,
5  title: `Title ${index}`,
6  description: `Description ${index}`,
7  items: Array.from({ length: 10 }).map((_, index) => ({
8    id: index,
9    title: `Item ${index}`,
10  })),
11}));
12
13function MainComponent() {
14  return (
15    <div className='w-full h-full'>
16      <VirtualizedGrid
17        totalRows={data.length}
18        totalColumns={10}
19        rowHeight={100}
20        columnWidth={100}
21        rowOverscanCount={3}
22        columnOverscanCount={3}
23        rowGap={10}
24        columnGap={10}
25      >
26        {data.map((row, rowIndex) => (
27          <div key={row.id} className='flex flex-col'>
28            {row.items.map((item, itemIndex) => (
29              <div key={item.id} className='flex flex-col'>
30                <h1>{item.title}</h1>
31              </div>
32            ))}
33          </div>
34        ))}
35      </VirtualizedGrid>
36    </div>
37  );
38}

Caveats

• The calculated size of the DynamicList is not "fully" dynamic. The component needs the user to supply a function that returns the size of each item based on the index. This is because calculating the height/width of each item automatically requires rendering them off-screen, which can be inefficient for large datasets.