Virtual List React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Virtual List is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import VirtualList from @/components/ui/virtual-list.

import { useRef } from "react"
import { ListItem } from "@/components/ui/list"
import { VirtualList, type VirtualListHandle } from "@/components/ui/virtual-list"

type Client = { id: string; name: string; city: string; balance: string }

const letter = (client: Client) => client.name.charAt(0).toLocaleUpperCase("en")

export function Clients({ clients, hasMore, loadPage }: { clients: Client[]; hasMore: boolean; loadPage: () => Promise<void> }) {
  const list = useRef<VirtualListHandle>(null)
  return (
    <div className="h-[560px]">
      <VirtualList
        aria-label="Clients"
        items={clients}
        getGroup={letter}
        renderItem={(client) => (
          <ListItem id={client.id} title={client.name} description={client.city} avatar={{ name: client.name }} value={client.balance} />
        )}
        hasMore={hasMore}
        onLoadMore={loadPage}
        persistKey="clients"
        handleRef={list}
        labels={{ end: "You reached the end" }}
      />
    </div>
  )
}

Props

• items*
  T[]

  Every loaded row. Append a page to load more; a shorter array (a filter) keeps the scroll position clamped.

• renderItem*
  (item: T, index: number) => ReactNode

  Renders one row, usually a <ListItem /> returned directly (not wrapped in your own component), so it inherits size and dividers and receives aria-posinset / aria-setsize. Keep images at a fixed size so rows measure right the first time.

• getItemKeydefault "item.id"
  (item: T, index: number) => string

  Stable row keys for measurement, selection and scroll restoration. Define it at module scope or with useCallback.

• getGroup
  (item: T) => string

  Consecutive items with the same key share a group header (32px, eyebrow style) that pins to the top while you are in that group. Letters for contacts, groupByDay keys for feeds. Unset: no headers.

• renderGroupHeaderdefault "the group string"
  (group: string, firstItem: T) => ReactNode

  The header content: "A", "Today", "September 2026".

• emptyStatedefault "<EmptyState preset="empty" size="sm" />"
  ReactNode

  Shown when there are no items, nothing is loading and nothing more can load.

• endMessagedefault ""
  ReactNode

  The quiet line after the last page (hasMore false and onLoadMore set). Empty uses labels.end ("You have reached the end"); null hides it.

• variantdefault "plain"
  "plain" | "inset"

  plain: rows on the page background. inset: one raised panel (the iOS grouped look) that is also the scroll box.

• sizedefault "md"
  "sm" | "md" | "lg"

  Row size passed to every ListItem: 44 / 56 / 64px, with matching avatars, header padding and skeletons.

• dividersdefault "inset"
  "full" | "inset" | "none"

  Hairlines between rows. inset starts after the icon or avatar; a group header starts a fresh run.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg"

  Corners of the inset panel: 0 / 12 / 16 / 24px.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  Selection color (checkboxes, the check mark) and the Load more button's tint.

• colordefault ""
  string

  Any CSS color; replaces the tone.

• scrolldefault "self"
  "self" | "window"

  self: the list scrolls inside height. window: the page scrolls (useWindowVirtualizer), or the nearest ScrollContainerProvider (an app shell's content column, a demo frame) when there is one.

• heightdefault "100%"
  number | string

  The scroll box height with scroll="self" (a number is px, any CSS length works). The server renders the rows that fit a px height, so hydration never jumps.

• estimateSizedefault "44 / 56 / 64 by size"
  number or ((index: number) => number)

  A first guess per row. Rows are measured after render (one-line and two-line descriptions both fit); a close guess only avoids a jump.

• overscandefault 8
  number

  Rows rendered past each edge of the viewport. More hides blank flashes on very fast flicks; fewer keeps the DOM smaller.

• stickyOffsetdefault 0
  number

  px between the scroll edge and the pinned group header, e.g. the height of a sticky app bar above a window list.

• loadingdefault false
  boolean

  The first load: skeleton rows in the real row shape (avatar, two lines) fill the viewport, and aria-busy is set.

• skeletonCountdefault 0
  number

  Skeleton rows while loading. 0 fills the scroll box (height / row estimate).

• hasMoredefault false
  boolean

  More pages exist. Turns on the loading footer (auto), the Load more button or the pull indicator, and makes aria-setsize -1 (unknown). The demo pages in 50 clients at a time when it is on and shows all 5,000 when it is off.

• loadingMoredefault false
  boolean

  Controlled flag for a page in flight. Not needed when onLoadMore returns a promise: that sets it automatically.

• error
  ReactNode

  A failed page load. With rows: an inline error row with Try again under them (the loaded rows stay, automatic loading pauses). Without rows: the error empty state. true uses labels.error.

• onRetry
  () => (void | Promise<unknown>)

  The Try again button of the error row.

• loadModedefault "auto"
  "auto" | "button" | "pull"

  auto: loads when the last row comes within threshold px (no gesture needed, the default). button: a full-width Load more button that shows its own spinner. pull: at the end, pull past 64px (rubberband, touch and trackpad) and let go.

• thresholddefault 600
  number

  px before the end at which auto mode asks for the next page, so it usually arrives before you get there.

• onLoadMore
  () => (void | Promise<unknown>)

  Asks for the next page. A returned promise drives the loading state; calls while a page is loading are ignored.

• onEndReached
  () => void

  Fires once per page when the bottom of the last row comes into view (analytics).

• persistKeydefault ""
  string

  Restores the scroll position (sessionStorage, anchored to a row so measured heights do not drift) when the list mounts again, e.g. after back navigation. Skipped when the first row changed.

• selectionModedefault "none"
  "none" | "single" | "multiple"

  Selectable rows, like List: the list becomes a listbox with one Tab stop, checkboxes (multiple) or a check (single). Ctrl / Cmd + A selects every row, rendered or not.

• selectedKeys
  string[]

  The selected row keys (controlled).

• defaultSelectedKeys
  string[]

  The initial selection (uncontrolled).

• onSelectedKeysChange
  (keys: string[]) => void

  Called with the new selection, in row order.

• selectionIndicatordefault "auto"
  "auto" | "checkbox" | "check" | "highlight"

  auto: a checkbox for multiple, a trailing check for single; highlight tints the row only.

• showChevrondefault true
  boolean

  Rows with href or onSelect end in a chevron.

• onAction
  (key: string, item: T) => void

  Row activation, after the row's own onSelect.

• handleRef
  RefObject<VirtualListHandle> or (handle: VirtualListHandle | null) => void

  { scrollToIndex(index, { align, smooth }), scrollToKey(key, options), scrollToTop({ smooth }), getVirtualizer() }. Indexes count items, not group headers; smooth turns off under reduced motion.

• onRangeChange
  (range: { startIndex; endIndex; rendered; total }) => void

  The visible item indexes and how many rows are in the DOM, whenever that changes (a position readout, analytics).

• localedefault ""
  string

  Formats the loaded-count announcement. Empty uses UIProvider, then the page language.

• labelsdefault "{ loadMore: "Load more", loading: "Loading…", end: "You have reached the end", pull: "Pull to load more", release: "Release to load", error: "Could not load more", retry: "Try again", empty: "Nothing here yet", loaded: (n, formatted) => `${formatted} more loaded` }"
  Partial<VirtualListLabels>

  Every string of the list itself; DEFAULT_VIRTUAL_LIST_LABELS is exported.

• listLabels
  Partial<ListLabels>

  Strings of the rows (the row menu button, the checkbox), passed to the list context.

• classNames
  Partial<Record<"content" | "inner" | "row" | "groupHeader" | "footer" | "loading" | "loadMore" | "pull" | "end" | "error" | "empty" | "skeleton", string>>

  Extra classes for the inner parts.

• className
  string

  Extra classes for the root (the scroll box with scroll="self"), merged last.

Parts

FAQ

More React table and list components