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

import { ListingCard, type ListingData } from "@/components/ui/listing-card"

const bike: ListingData = {
  id: "l01",
  title: "Trek FX 2 city bike",
  href: "/listings/l01",
  images: ["/demo/bicycle.jpg"],
  price: 280,
  currency: "USD",
  priceType: "negotiable",
  location: "Portland, Pearl District",
  postedAt: "2026-09-24T14:32:00",
  delivery: true,
  condition: "used",
  seller: { name: "Daniel Reed", verified: true, rating: 4.8 },
}

export function SearchResult({ onSave }: { onSave: (id: string, saved: boolean) => Promise<void> }) {
  return (
    <ListingCard
      listing={bike}
      size="sm"
      showSeller
      locale="en-US"
      onFavoriteChange={(saved, listing) => onSave(listing.id, saved)}
      labels={{ delivery: "Ships", price: { negotiable: "OBO" } }}
    />
  )
}

Props

• listing*
  ListingData

  The ad: { id, title, href?, images?: (string | { src, alt?, width?, height? })[], price (null: on request), currency?, compareAtPrice?, priceType?, priceSuffix?, unit?: { quantity, unit }, location?, distanceKm?, postedAt?, promoted?, delivery?, condition?: "new" | "used", attributes?: string[], badges?: { label, tone?, icon? }[], seller?: { name, avatar?, business?, verified?, rating? }, status?: "active" | "reserved" | "sold" | "expired", favorite?, favoriteCount? }.

• layoutdefault "grid"
  "grid" | "list" | "compact"

  grid: the photo on top (result grids). list: the photo at the start, a 112px square while the card is narrow and 240px wide in imageAspect once the card is 560px wide (search results). compact: a 64px thumbnail row with no carousel and no distance (recently viewed, a seller's other listings). ListingCardSkeleton (see Parts) has the same layouts for loading states.

• variantdefault "elevated"
  "elevated" | "outline" | "soft" | "ghost"

  The card surfaces: a raised panel, a hairline frame or the flat gray tile. ghost has no surface: a rounded photo with the text under it, like a fashion grid.

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

  Paddings, title and price size. sm is for two-column phone grids, lg for a featured listing.

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

  Card corners: 12 / 16 / 24px. The photo of a list row or a ghost card takes the matching inner corner.

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

  The photo box in grid and list layouts (list rows stay square on phones). 3/4 suits fashion, 16/10 cars and homes.

• maxImagesdefault 5
  number

  Photos in the card's carousel. 1 shows a single photo with no swipe: use it for cards inside horizontal rails, which must never nest a carousel. When the listing has more photos, a camera chip shows the real total.

• showDotsdefault true
  boolean

  Dots under the photo (at most five, sliding along with the photo), over a soft shade so they read on any image.

• showArrowsdefault true
  boolean

  Previous / next buttons on the photo. They appear while the card is hovered or holds focus, on fine pointers only (phones swipe).

• showFavoritedefault true
  boolean

  The heart: round glass on the photo in the grid layout, a plain icon button at the end of list and compact rows.

• defaultFavoritedefault false
  boolean

  Starts saved (uncontrolled). Falls back to listing.favorite.

• favorite
  boolean

  Controlled saved state; pair it with onFavoriteChange.

• onFavoriteChange
  ((favorite: boolean, listing: ListingData) => void | Promise<unknown>)

  Called when the heart toggles. Return a promise to keep the heart in its new state while it is pending; a rejection rolls it back, shakes it and announces the error.

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

  The saved heart's color. Neutral is white on photos and black / white elsewhere; danger gives the classic red heart.

• showBadgesdefault true
  boolean

  The promoted chip on the photo and the small badges under the text: delivery, new or used, business seller and listing.badges.

• showAttributesdefault true
  boolean

  The attributes line ("2019 · 51,000 mi · Gasoline"): one line in grids, up to two in list rows.

• showSellerdefault false
  boolean

  The seller line: a small avatar, the name, a check when verified and the rating. In grids it sits at the bottom, over a hairline.

• promotedStyledefault "badge"
  "badge" | "ring" | "both"

  How a promoted listing stands out: a labelled chip on the photo, a 2px ring in promotedTone around the card, or both.

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

  The promoted chip and ring color. Promotion is a status, so it defaults to the amber warning tone; the chip always says it in words.

• timeFormatdefault "day"
  "day" | "relative" | "date"

  day: "Today at 2:32 PM", "Yesterday at 9:10 AM", then "Sep 22" this year and the full date before. relative: "2 hours ago". date: the short numeric date. The full date and time is in the tooltip. formatListingTime (see Parts) prints the same text outside the card.

• prioritydefault false
  boolean

  Loads the first photo eagerly with high fetch priority. Set it on the first row of a grid; every other photo loads lazily.

• localedefault ""
  string

  Formats the price, distance and time ("$1,200", "4.2 km", "2:32 PM" in en-US). Empty uses the UIProvider locale, then the page.

• hrefdefault ""
  string

  Where the card leads; empty uses listing.href. Rendered through linkComponent, so a Next.js Link keeps client navigation. The playground's pretend router prints it.

• onSelect
  (listing: ListingData) => void

  Without an href, the title becomes a button that calls it (and a click anywhere on the card does too). Without both, the card is not interactive.

• actions
  ReactNode

  Controls at the top end of the text ("⋯" on your own listings, an edit button). They sit above the stretched link, so a click on them never opens the listing.

• nowdefault "useNow()"
  number | null

  The reference time in ms for "Today at 2:32 PM". Pass the page's clock (one useNow() in the grid) so the cards re-render with it; without it every card on the page shares one minute timer (not one each). null prints dates.

• linkComponent
  (props: LinkComponentProps) => ReactNode

  The router link for the title and the photos. Defaults to the one given to LinkProvider (lib/navigation), else a plain <a>.

• labels
  Partial<ListingCardLabels>

  Copy, English by default: promoted, delivery, new, used, business, verified, reserved, sold, expired, today, yesterday, at, photo(title, i, n) (alt text), photos(n), noImage, distance(formatted), previous, next, rating(formatted), plus price (forwarded PriceLabels) and favorite (forwarded FavoriteButtonLabels). Pass only the keys you translate.

• classNames
  Partial<Record<"media" | "image" | "carousel" | "dots" | "favorite" | "body" | "title" | "price" | "attributes" | "meta" | "tags" | "seller" | "actions" | "status", string>>

  Extra classes for the inner parts.

• className
  string

  Extra classes for the card (the <article>), merged last.

Parts

FAQ

Used in

More React commerce components