Listing grid 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

Listing grid 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 ListingGrid from @/components/ui/listing-grid.

import { useState } from "react"
import { ListingGrid } from "@/components/ui/listing-grid"
import type { ListingData } from "@/components/ui/listing-card"

export function SearchResults({
  first,
  total,
  fetchPage,
}: {
  first: ListingData[]
  total: number
  fetchPage: (page: number, sort: string) => Promise<ListingData[]>
}) {
  const [items, setItems] = useState(first)
  const [sort, setSort] = useState("newest")
  const [page, setPage] = useState(1)

  return (
    <ListingGrid
      items={items}
      total={total}
      sort={sort}
      onSortChange={async (next) => {
        setSort(next)
        setPage(1)
        setItems(await fetchPage(1, next))
      }}
      hasMore={items.length < total}
      onLoadMore={async () => {
        const next = await fetchPage(page + 1, sort)
        setPage(page + 1)
        setItems((current) => [...current, ...next])
      }}
      viewPersistKey="listings-view"
      locale="en-US"
      sortOptions={[
        { value: "newest", label: "Newest" },
        { value: "price-asc", label: "Price: low to high" },
        { value: "price-desc", label: "Price: high to low" },
        { value: "relevance", label: "Most relevant" },
      ]}
      labels={{ end: "That's every listing" }}
    />
  )
}

Props

• items*
  ListingData[]

  The listings loaded so far, in order. Appending a batch animates the new cards in; replacing the set (a new search, a sort) swaps without animation.

• renderItem
  (item: ListingData, context: { view: ListingGridView; index: number; promoted: boolean }) => ReactNode

  Replaces the default ListingCard for each item (a custom card, an ad slot every 12 items). Items of the promoted block come with promoted true and view grid.

• cardProps
  Partial<ListingCardProps>

  Passed to every default card: the favorite handler, labels, the page's now, promotedStyle. Wins over the grid's own card settings.

• defaultViewdefault "grid"
  "grid" | "list"

  The starting view while uncontrolled. List shows one column of list rows (a 112px photo on phones) up to 896px wide.

• view
  "grid" | "list"

  The controlled view; pair it with onViewChange.

• onViewChange
  (view: ListingGridView) => void

  Called when the header's switch changes the view.

• viewPersistKeydefault ""
  string

  Remembers the view in localStorage under this key, so a visitor who prefers the list keeps it. Empty keeps it in memory.

• showViewSwitchdefault true
  boolean

  The grid / list switch in the header: a segmented control on wide headers, one toggle button on narrow ones.

• columnsdefault "{ base: 2, md: 3, lg: 4 }"
  ListingGridColumns = { base?; sm?; md?; lg?; xl? }

  Columns by the grid's own width (base, then 640 / 768 / 1024 / 1280px and up); a missing step inherits the smaller one. CSS variables and container queries, so the server layout is already right and a grid next to a filter sidebar gets fewer columns.

• gapdefault "md"
  "sm" | "md" | "lg"

  Space between cards: 8px; 12px (16px from 768px of grid width); 16px (24px from 768px).

• cardSizedefault "auto"
  "auto" | "sm" | "md" | "lg"

  The cards' size. auto: sm while the grid is narrower than 768px (two-column phone grids), md from there; list rows stay md so the photo keeps 112px.

• cardVariantdefault "elevated"
  "elevated" | "outline" | "soft" | "ghost"

  The cards' surface; ghost drops it for a photo-first grid (fashion, Vinted style).

• imageAspectdefault "4/3"
  "1/1" | "4/3" | "3/2" | "16/10" | "3/4"

  The photo shape of every card and skeleton.

• totaldefault 0
  number

  The full result count ("1,240 listings" in the header, "Showing 24 of 1,240" under the button). 0 means unknown: the count and the "of N" disappear and the button still offers more while hasMore. The playground fills in its live count at 0.

• defaultSortdefault "newest"
  string

  The starting sort while uncontrolled, one of sortOptions' values. The playground really sorts its 1.240 results.

• sort
  string

  The controlled sort; pair it with onSortChange.

• onSortChange
  (sort: string) => void

  Called with the picked value. Fetch the sorted first page and replace items; the grid scrolls its header back into view.

• sortOptionsdefault "DEFAULT_LISTING_SORT_OPTIONS"
  { value: string; label: ReactNode }[]

  The sort menu: newest "Newest", price-asc "Price: low to high", price-desc "Price: high to low", relevance "Most relevant". An empty array hides the sort.

• appliedFilters
  ToolbarAppliedFilter[]

  Removable chips under the header ({ id, label }: "Portland +25 km", "Price: $200 to $3,000"). filter-panel's describeFilters builds them.

• onRemoveFilter
  (id: string) => void

  Called by a chip's ×.

• onClearFilters
  () => void

  Adds "Clear filters" after the chips and to the no-results state.

• filterTrigger
  ReactNode

  The phone "Filtre (3)" button that opens your filter sheet; hide it from 768px (md:hidden) when a sidebar takes over.

• showHeaderdefault true
  boolean

  The header with the count, sort, view switch, save search and the chips.

• stickyHeaderdefault false
  boolean

  The header sticks under the top bar (top: var(--topbar-offset, 0px)) on glass, with a hairline once stuck. Scroll the playground to see it.

• toolbarProps
  Partial<ToolbarProps>

  Anything else for the header's Toolbar: size, radius, variant (surface for a raised panel), even a search field.

• promoted
  ListingData[]

  A "Promoted" block above the results: a swipeable rail below 768px of grid width (one photo per card on touch, so swipes never nest), the first grid row from there.

• loadingdefault false
  boolean

  First load: skeleton cards with the real card shape in place of the list (aria-busy on the list), and one announcement.

• skeletonCountdefault 8
  number

  Skeleton cards while loading.

• hasMoredefault false
  boolean

  Whether there are more listings to load. False with an onLoadMore shows "You have seen all listings". The playground turns it on while its data has more; the control forces it.

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

  Loads the next batch and appends it to items. A returned promise keeps the button busy until it settles.

• loadingMoredefault false
  boolean

  The next batch is loading (the footer button shows its spinner). Ignored without hasMore.

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

  auto: loads when the end comes within 200px of the scroll container's edge, with the button kept as the fallback; button: on click only.

• pageSizedefault 24
  number

  Listings per batch, for the button label ("Show 24 more", fewer near the end when total is known).

• error
  ReactNode

  An error message. With no items it replaces the list ("Try again" when onRetry is set); after a failed batch it takes the footer's place under the loaded cards.

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

  The error state's "Try again"; a returned promise keeps it busy.

• emptyStatedefault "EmptyState preset="no-results""
  ReactNode

  Replaces the no-results state (by default "No listings match" with "Clear filters" when onClearFilters is set).

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

  Shows a bell "Save search" button in the header (icon-only on narrow headers). A returned promise keeps it busy.

• savedSearchdefault false
  boolean

  The save button's saved state: "Search saved" with a ringing bell, aria-pressed.

• animateIndefault true
  boolean

  New batches rise in with a 30ms stagger (the first 12 of each batch; a fade only under reduced motion). A replaced or re-sorted set never animates.

• localedefault ""
  string

  Formats the counts; defaults to the app's locale (UIProvider), then the browser's. Passed on to the cards.

• labelsdefault "DEFAULT_LISTING_GRID_LABELS"
  Partial<ListingGridLabels>

  Every string, English by default: results (n, formatted), sort, view, grid, list, promoted, loadMore (n, formatted), remaining (n, formatted), showing (shown, total), loaded (n, formatted), loading, end, saveSearch, searchSaved, clearFilters, appliedFilters, removeFilter, cancel (the phone sort sheet), emptyTitle, emptyDescription, errorTitle, retry.

• classNames
  Partial<Record<"header" | "promoted" | "items" | "item" | "footer" | "empty", string>>

  Extra classes for the inner parts.

• className
  string

  Extra classes for the root, merged last.

Parts

FAQ

Used in

More React commerce components