Posted on Apr 23

Building an Efficient Virtualized Table with TanStack Virtual and React Query with ShadCN

When displaying large datasets in a table, performance and smooth scrolling become critical challenges. That's where TanStack Virtual (formerly known as react-virtual) and React Query come into play. In this guide, we'll walk through building a virtualized table that fetches paginated data and provides a seamless user experience.

Step 1: Fetching Paginated Data with React Query
First, we need to fetch our data efficiently using React Query. We'll define a query that retrieves companies' data based on pagination.

const { data, isLoading, error, isFetching } = useQuery<CompanyResponse>({ queryKey: ["companies", searchParameters.toString(), itemsPerPage], queryFn: () => fetchCompanies( currentPage.toString(), itemsPerPage.toString(), ), });

queryKey ensures proper caching and refetching when parameters change.
queryFn is the function that actually fetches the data.
make a queryFn for fetching data

Step 2: Implementing a "Load More" Pagination

Instead of traditional pagination, we'll use a "Load More" approach that increases the number of items fetched.

const handleLoadMore = () => { setItemsPerPage((previous) => previous + PAGE_INCREMENT); };

This makes it feel like an infinite scroll experience without dealing with page numbers manually.

Step 3: Setting Up Virtualization with TanStack Virtual
Next, we use TanStack Virtual to render only the visible rows, dramatically improving performance.

const virtualizer = useVirtualizer({ count: data?.companies.length || 0, estimateSize: () => 40, // Average row height getScrollElement: () => scrollContainerRef.current, }); const virtualRows = virtualizer.getVirtualItems(); const visibleCompanies = virtualRows .map((virtualRow) => data?.companies[virtualRow.index]) .filter(Boolean);

Here:

count is the total number of companies we fetched.
estimateSize gives the virtualizer a rough idea of row height.
getScrollElement provides the scrollable container.

Step 4: Defining Table Columns
Now, let's define the table columns with appropriate headers and cell renderers.

const tableColumns: ColumnDef<Company | undefined>[] = [ { accessorKey: "name", header: () => <div>Company Name</div>, cell: ({ row }) => <div>{row.original?.name}</div>, }, { accessorKey: "phone", header: () => <div>Phone Number</div>, cell: ({ row }) => <div>{row.original?.phone}</div>, }, { accessorKey: "email", header: () => <div>Email</div>, cell: ({ row }) => <div>{row.original?.email}</div>, }, { accessorKey: "location", header: () => <div>Location</div>, cell: ({ row }) => <div>{row.original?.address.state}</div>, }, { accessorKey: "products", header: () => <div>Products</div>, cell: ({ row }) => ( <div className="flex items-center gap-2"> <UserIcon /> {row.original?.productsCount} </div> ), }, { accessorKey: "actions", header: () => <div>Actions</div>, cell: () => ( <div className="flex gap-2"> <button>Details</button> </div> ), }, ];

Step 5: Handling Loading and Error States
Before rendering the table, we need to handle loading, error, or empty states gracefully.

if (isLoading) return <LoadingSkeleton />; if (error) return <div>Error loading data</div>; if (!data) return <div>No data available</div>;

Step 6: Rendering the Virtualized Table
Here comes the main part: rendering the virtualized list inside a scrollable container.

<section> <div ref={scrollContainerRef} className="relative h-[400px] overflow-auto rounded-md" > <div style={{ height: virtualizer.getTotalSize(), position: "relative", }} > <div style={{ position: "absolute", top: 0, left: 0, width: "100%", transform: `translateY(${virtualRows[0]?.start ?? 0}px)`, }} > <CustomTable columns={tableColumns} data={visibleCompanies} /> </div> </div> </div> </section>

Here’s what happens:

We create a scrollable container (overflow-auto) with a fixed height.
The total container height (getTotalSize()) matches the total rows' size.
Only the visible portion (translateY) moves according to the current scroll.

Step 7: Adding a Load More Button
At the bottom, we add a "Load More" button to fetch more data dynamically.

<section className="flex justify-center mt-4"> <Button onClick={handleLoadMore} disabled={isFetching || (data && data.companies.length >= data.totalCount)} > {isFetching ? "Loading..." : "Load More"} </Button> </section>

By combining React Query for efficient data fetching and TanStack Virtual for rendering optimization, we've built a fast, scalable, and user-friendly table even for large datasets.

Key Takeaways:

Virtualization avoids rendering all rows at once, saving memory and improving performance.
Pagination with a "Load More" button makes loading large lists intuitive.
Loading and error handling ensures a smooth user experience.

Here is the ShadCN table Component

//custom table "use client"; import { ColumnDef, flexRender, getCoreRowModel, useReactTable, } from "@tanstack/react-table"; import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow, } from "@/components/ui/table"; interface DataTableProps<TData, TValue> { columns: ColumnDef<TData, TValue>[]; data: TData[]; } export function CustomTable<TData, TValue>({ columns, data, }: DataTableProps<TData, TValue>) { const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel(), }); return ( <div className="rounded-md border overflow-x-auto"> <Table className="min-w-full table-fixed"> <TableHeader className="bg-muted text-muted-foreground"> {table.getHeaderGroups().map((headerGroup) => ( <TableRow key={headerGroup.id}> {headerGroup.headers.map((header) => ( <TableHead key={header.id} className="whitespace-nowrap px-4 py-2 text-left" style={{ width: "150px" }} // 👈 FIX WIDTH HERE > {header.isPlaceholder ? null : flexRender( header.column.columnDef.header, header.getContext() )} </TableHead> ))} </TableRow> ))} </TableHeader> <TableBody> {table.getRowModel().rows?.length ? ( table.getRowModel().rows.map((row) => ( <TableRow key={row.id} data-state={row.getIsSelected() && "selected"} > {row.getVisibleCells().map((cell) => ( <TableCell key={cell.id} className="whitespace-nowrap px-4 py-2" style={{ width: "150px" }} // 👈 FIX WIDTH HERE TOO > {flexRender(cell.column.columnDef.cell, cell.getContext())} </TableCell> ))} </TableRow> )) ) : ( <TableRow> <TableCell colSpan={columns.length} className="h-24 text-center"> No results. </TableCell> </TableRow> )} </TableBody> </Table> </div> ); }