# Seller card

> A React seller card for marketplaces: avatar, verified mark, stars, reply speed, a phone number to reveal, message, follow, more listings.

- Type: React component (Commerce)
- Access: Pro (the source needs a Wingo UI Pro plan, see https://wingo-ui.com/pricing)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add seller-card`
- Docs: https://wingo-ui.com/components/seller-card

## Interaction

Tap the call button to show the seller's number: it fetches the full number (a spinner holds the button's width), the digits fade in, and the button turns into a real phone link, so the next tap dials. With a mouse a copy button appears beside the revealed number. If the number cannot be fetched, the button goes back to masked and a short message says so. Tap Message to start a conversation. Tap Follow to follow the seller: a check draws itself, and it rolls back if saving fails. The name opens the seller's profile; hover or focus it to see what was verified (on touch the same list sits in the stats). The compact row is one big tap target that opens the profile. The other listings are compact rows, or a rail you swipe (drag with a mouse, Left / Right while it has focus). Keyboard: Tab reaches the name, Follow, the call and message buttons, the listings and See all; Enter or Space activates, and focus stays on the call button when it becomes a link. The revealed number and errors are announced. In a narrow two-column bar the call button drops its icon so the digits fit.

## Installation

```bash
npx wingo-ui@latest add seller-card
```

Pro item: run `npx wingo-ui@latest login` once with a Pro account. The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add @wingo-ui/seller-card` (needs the @wingo-ui registry with your API key in components.json)

Files:

- `components/ui/seller-card.tsx`

npm dependencies: `npm i lucide-react motion`

Wingo UI dependencies (installed automatically):

- [Avatar](https://wingo-ui.com/components/avatar) ([Markdown](https://wingo-ui.com/components/avatar.md))
- [Badge](https://wingo-ui.com/components/badge) ([Markdown](https://wingo-ui.com/components/badge.md))
- [Button](https://wingo-ui.com/components/button) ([Markdown](https://wingo-ui.com/components/button.md))
- [Carousel](https://wingo-ui.com/components/carousel) ([Markdown](https://wingo-ui.com/components/carousel.md))
- [Copy Button](https://wingo-ui.com/components/copy-button) ([Markdown](https://wingo-ui.com/components/copy-button.md))
- [Listing card](https://wingo-ui.com/components/listing-card) ([Markdown](https://wingo-ui.com/components/listing-card.md))
- [Rating](https://wingo-ui.com/components/rating) ([Markdown](https://wingo-ui.com/components/rating.md))
- [Tooltip](https://wingo-ui.com/components/tooltip) ([Markdown](https://wingo-ui.com/components/tooltip.md))
- [useControllableState](https://wingo-ui.com/components/use-controllable-state) ([Markdown](https://wingo-ui.com/components/use-controllable-state.md))
- [useLocale](https://wingo-ui.com/components/use-locale) ([Markdown](https://wingo-ui.com/components/use-locale.md))
- [Date utils](https://wingo-ui.com/components/date-utils) ([Markdown](https://wingo-ui.com/components/date-utils.md))
- [Motion presets](https://wingo-ui.com/components/motion) ([Markdown](https://wingo-ui.com/components/motion.md))
- [Navigation](https://wingo-ui.com/components/navigation) ([Markdown](https://wingo-ui.com/components/navigation.md))
- [Number format](https://wingo-ui.com/components/number-format) ([Markdown](https://wingo-ui.com/components/number-format.md))
- [Relative time](https://wingo-ui.com/components/relative-time) ([Markdown](https://wingo-ui.com/components/relative-time.md))
- [Tones](https://wingo-ui.com/components/tones) ([Markdown](https://wingo-ui.com/components/tones.md))
- [UIProvider](https://wingo-ui.com/components/ui-config) ([Markdown](https://wingo-ui.com/components/ui-config.md))

## Usage

```tsx
import { SellerCard, type SellerData } from "@/components/ui/seller-card"

const mihai: SellerData = {
  id: "s-mihai",
  name: "Michael Reed",
  avatar: "/demo/mihai-ionescu.jpg",
  href: "/sellers/mihai-ionescu",
  type: "private",
  verified: { phone: true, identity: true },
  rating: 4.8,
  reviewCount: 126,
  memberSince: "2019-03-12",
  responseRate: 0.98,
  responseTime: 40,
  location: "Brooklyn",
  listingCount: 14,
  phone: "07700 900 •••",
}

export function ListingSidebar({ openChat }: { openChat: () => void }) {
  return (
    <SellerCard
      seller={mihai}
      callingCode="44"
      onRevealPhone={async () => {
        const response = await fetch("/api/listings/l01/phone", { method: "POST" })
        return (await response.json()).phone as string
      }}
      onMessage={openChat}
      listingsHref="/sellers/mihai-ionescu"
      labels={{ showNumber: "Reveal number", message: "Chat" }}
    />
  )
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `seller` | `SellerData` |  | The seller: { id, name, avatar?, href?, type?: "private" \| "business", companyName?, cui?, agent?, verified?: boolean \| { phone?, identity?, company? }, rating? (0 to 5), reviewCount?, memberSince?, responseRate? (0 to 1), responseTime? (minutes), lastSeen?: time \| "online", location?, listingCount?, phone? }. |
| `variant?` | `"card" \| "compact" \| "inline"` | `"card"` | card: the side column of a detail page with stats, contact and listings. compact: avatar, name, rating, one stat and a chevron as one tappable row (the phone detail page). inline: a small avatar, the name, the verified mark and a star on one line, no surface. |
| `size?` | `"sm" \| "md" \| "lg"` | `"md"` | Avatar 40 / 48 / 64px in the card, the type scale, paddings and the contact buttons (md in sm, 48px lg otherwise). |
| `radius?` | `"sm" \| "md" \| "lg"` | `"md"` | The surface corner: 12 / 16 / 24px. The buttons and listing tiles inside follow it. |
| `tone?` | `"neutral" \| "brand" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | The call button (solid) and the message button (soft of the same tone). |
| `color?` | `string` | `""` | Any CSS color for the contact buttons; replaces the tone. |
| `ratingTone?` | `"neutral" \| "brand" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | The stars' fill. warning gives the classic amber stars. |
| `showStats?` | `boolean` | `true` | The card's facts: private or business (with the tax id), what was verified, member since, reply time, response rate, place, last activity, listing count. |
| `showRating?` | `boolean` | `true` | Stars, the value and the review count; a seller without reviews gets a "New seller" badge instead. |
| `showContact?` | `boolean` | `true` | The call and message buttons (SellerContactActions) in the card. |
| `showFollow?` | `boolean` | `false` | A Follow toggle in the card's header: icon only in a narrow card, with its label from 400px. |
| `defaultFollowing?` | `boolean` | `false` | Starts followed (uncontrolled). Use following + onFollowingChange to control it. |
| `following?` | `boolean` |  | The controlled follow state. |
| `onFollowingChange?` | `(following: boolean) => (void \| Promise<unknown>)` |  | Called on every toggle. Return a promise: a rejection rolls the toggle back and announces labels.followError. |
| `onRevealPhone?` | `() => (string \| Promise<string>)` |  | Show number fetches the full number (marketplaces log reveals). A spinner shows while it runs; a rejection returns the button to masked and says labels.revealError. Without it seller.phone is revealed on tap. The revealed number is kept per seller.id for the page's life, so a sticky contact bar shows it too. |
| `onCall?` | `(phone: string) => void` |  | Replaces the tel: link of the revealed number (open a call sheet, log the call). |
| `onMessage?` | `() => void` |  | The Message button. Without it and without messageHref there is no Message button. |
| `messageHref?` | `string` | `""` | Makes Message a link to the conversation. |
| `callingCode?` | `string` | `""` | The country calling code for the tel: link: "44" turns 07700 900 123 into tel:+447700900123. Empty keeps the number as written. |
| `contactLayout?` | `"row" \| "stack" \| "auto"` | `"auto"` | Call and Message side by side, stacked, or auto: stacked while the card is under 400px wide (a sidebar, a phone), side by side above. |
| `listings?` | `ListingData[]` |  | The seller's other listings (ListingData from listing-card), shown under the contact buttons. |
| `showListings?` | `boolean` | `true` | The listings section, when there are listings. |
| `listingsHref?` | `string` | `""` | The "See all (14)" link beside the heading; the count is seller.listingCount. |
| `listingLayout?` | `"compact" \| "grid"` | `"compact"` | Compact listing rows, or a swipeable rail of small grid cards with one photo each (no carousel inside a carousel). |
| `maxListings?` | `number` | `3` | How many listings to show. |
| `listingsLoading?` | `boolean` | `false` | Skeleton rows in place of the listings while they load. |
| `compactStat?` | `"auto" \| "lastSeen" \| "memberSince" \| "responseTime" \| "location" \| "listings"` | `"auto"` | The one fact beside the rating in the compact row. auto: the last activity, else the reply time, the place, then member since. |
| `onSelect?` | `(seller: SellerData) => void` |  | Without seller.href, the compact row and the name become buttons that call it. |
| `now?` | `number \| null` |  | The page's clock in ms for "Active 5 minutes ago". Defaults to a shared minute timer (useNow); null prints dates. A timestamp, so it stays out of the playground. |
| `linkComponent?` | `(props: LinkComponentProps) => ReactNode` |  | The router link for the name, the compact row, Message, See all and the listings. Defaults to the LinkProvider's, then <a>. |
| `locale?` | `string` | `""` | Numbers, dates and relative times. Empty uses the UIProvider locale, then the browser's. |
| `labels?` | `Partial<SellerCardLabels>` |  | Every string, English by default (DEFAULT_SELLER_CARD_LABELS): verified, verifiedIdentity, verifiedPhone, verifiedCompany, business, private, newSeller, memberSince(date), responseRate(percent), responseTime(text), withinHour, withinDay, online, lastSeen(text), listings(n, formatted), reviews(n, formatted), rating(value), agent(name), cui, call, callSeller(name), showNumber, revealNumber(name), message, messageSeller(name), copyNumber, copiedNumber, revealed(phone), revealError, follow, following, followError, otherListings, seeAll(n, formatted), loadingListings, the hidden stat names (statType, statVerification, statMemberSince, statResponseTime, statResponseRate, statLocation, statActivity, statListings, statAgent) and listing (forwarded ListingCardLabels). |
| `classNames?` | `Partial<Record<"header" \| "avatar" \| "name" \| "verified" \| "type" \| "rating" \| "stats" \| "stat" \| "contact" \| "call" \| "message" \| "follow" \| "listings", string>>` |  | Extra classes for the inner parts. |
| `className?` | `string` |  | Extra classes for the root, merged last. |

## Parts

### SellerContactActions (component)

The call / message pair on its own, with the same reveal (shared per seller.id with every card on the page). It is what a listing page's sticky contact bar holds as its action. Props: { seller?, phone?, onRevealPhone?, onCall?, onMessage?, messageHref?, callingCode?, layout?: "row" | "stack" | "auto" = "row", size?: "sm" | "md" | "lg" = "lg", radius?, tone?, color?, showCopy? = true, linkComponent?, labels?, classNames? }.

### maskPhone (function)

Keeps the first `visible` digits (7) and the formatting: "0745 123 456" becomes "0745 123 •••". A masked number passes through. Signature: (phone: string, visible?: number) => string.

### DEFAULT_SELLER_CARD_LABELS (constant)

The English strings; spread them to translate a few. Type: SellerCardLabels.

## Examples

- **Business seller**: Green House Realty: a Business badge, the tax ID, the agent, amber stars and a rail of listings.
- **Compact row on a phone**: One tappable row under the listing that opens the seller's profile.
- **Inline in a listing card**: The small avatar, name, verified mark and stars as a card footer.
- **New seller**: No reviews yet: a New seller badge instead of stars, joined in August 2026.
- **Reveal failing**: The fetch fails, the button returns to masked and the error is shown and announced.
- **Contact actions in a bottom bar**: SellerContactActions on its own, next to a favorite button, as a sticky contact bar holds it.
- **Follow and a brand call**: An optimistic follow toggle whose check draws itself, and tone brand on the call button.

## See also

- [Listing card](https://wingo-ui.com/components/listing-card) ([Markdown](https://wingo-ui.com/components/listing-card.md))
- [Reviews](https://wingo-ui.com/components/reviews) ([Markdown](https://wingo-ui.com/components/reviews.md))
- [Sticky CTA Bar](https://wingo-ui.com/components/sticky-cta-bar) ([Markdown](https://wingo-ui.com/components/sticky-cta-bar.md))
- [Product gallery](https://wingo-ui.com/components/product-gallery) ([Markdown](https://wingo-ui.com/components/product-gallery.md))
- [Rating](https://wingo-ui.com/components/rating) ([Markdown](https://wingo-ui.com/components/rating.md))
- [Avatar](https://wingo-ui.com/components/avatar) ([Markdown](https://wingo-ui.com/components/avatar.md))

---

Canonical: https://wingo-ui.com/components/seller-card
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt