# Product Card

A shop tile with image, name, price and rating, plus optional wishlist and add-to-cart buttons.

- Category: Commerce
- Page: https://wunderui.com/components/product-card
- Tier: Core and Pro

## Install

Product Card ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { ProductCard, ProductCardProps, ProductMiniCard } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { ProductCard } from "@wunderui/react"

export function Product() {
  return <ProductCard name="Standing desk Pro" price="$489.00" tint="indigo" className="w-60" />
}
```

Expected result: You should see a 240 px wide tile with an indigo image area and a package icon, the name Standing desk Pro in medium text and the price $489.00 under it.

## When to use

### Use Product Card for

- A grid of products in a shop or a category page
- A wishlist or a row of recommended products
- A product with a sale price, a badge and a quick add to cart

### Use something else

- [Product Mini Card](https://wunderui.com/components/product-mini-card) for a compact row with a small image and a quick add button
- [Item Card](https://wunderui.com/components/item-card) for one object with a description and its own action, without a price
- [Card](https://wunderui.com/components/card) for a free container for any content, with a header, a body and a footer

## Keyboard

A card has up to three tab stops, in order: the open button over the image, the wishlist heart and the add-to-cart button. Each exists only when its handler is set.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the next or previous control: open, wishlist, add to cart, then the next card. |
| `Enter` or `Space` | Presses the focused button and calls `onClick`, `onWishlist` or `onAddToCart`. |

## Behavior

What the card does with state, content, the DOM and motion.

- **Three controls in one card:** A click handler adds a transparent button over the image, a wishlist handler adds the heart and an add-to-cart handler adds the button. They are siblings, and only the image opens the product.
- **Content lines:** The price always shows. The last line is availability when sold out or set, otherwise the rating with its review count (ratings are clamped to 0 to 5), otherwise nothing.
- **Wishlist:** A wishlisted card fills the heart and sets aria-pressed, and the button keeps one name, Wishlist, so the label never flips between Add and Remove. The card does not keep the state.
- **Sold out and loading:** Sold out draws a grey badge, shows availability in the error colour and drops the add-to-cart button. Loading swaps the card for a skeleton and marks it busy; there is no hover or disabled look.
- **Image and errors:** The image is cropped to 7:4 and has an empty alt text, since the name sits under it. With no image or a broken address, the area falls back to the tint and a package icon.
- **Long text and width:** The card fills its container and the image keeps its ratio. The name and price row wrap, and nothing is cut with an ellipsis, so a card with a long name is taller than its neighbours.
- **Focus:** The heart, the add-to-cart button and the image button show the standard focus ring. The image button's ring follows the 16 px corners.
- **Motion and reduced motion:** The card does not animate. The buttons change colour on hover and press, which is not movement and stays the same under reduced motion.

## Anatomy

- `ProductCard`: Stacks the image, the text and the button with 12 px between them. It has no border or background, fills the width it is given, and is not a link or button itself.
- `Image`: A Product Image with a 7:4 ratio and a 16 px radius, showing the photo or a tint with an icon when there is none. With a click handler, a transparent button named after the product covers it.
- `Badge`: A pill on the top left of the image, 12 px from the edges, red unless you set another colour. When sold out it becomes a grey Sold out pill and replaces the badge.
- `Wishlist button`: A 32 px round icon button on the top right of the image, shown when a wishlist handler is set. The heart fills in the error colour while wishlisted.
- `Name`: The name in 14 px medium text. It wraps onto more lines when it is long.
- `Price`: A small Price with the price and, if set, the old price crossed out beside it.
- `Rating or availability`: One line of 11 px text: when sold out, availability in the error colour (Currently unavailable by default); else availability in the success colour; else the Stars, rating and count.
- `Add to cart button`: A full-width dark button, 32 px high, shown when an add-to-cart handler is set but not while sold out. Its text is the add-to-cart label.
- `ProductMiniCard`

## Best practices

### When to use

- Use Product Card for a grid of products, a wishlist or a row of recommendations. For a compact row with a quick add button, use Product Mini Card.

### Do

- Pass a click handler to open the product from the image, and make the name a link yourself if the product has its own page. The card is not a link, so call your router in the handler.
- Keep the wishlist in your own state. The wishlisted value and its handler are controlled, so the card does not change the heart by itself.
- Mark a product that cannot be bought as sold out: the card shows a grey badge and a red availability line and drops the add-to-cart button. Say when it is back, such as Back in stock Dec 4.
- When a page holds many cards, put the product name in the add-to-cart label as hidden text. Otherwise every button reads the same.
- Place the cards in a grid with a minimum column width, such as 10 rem, so image and text stay readable on a narrow screen.
- Pass loading while products load. Each card becomes a skeleton of the same shape, so the grid does not jump, and name and price are not needed.

### Don't

- Don't pass a rating and availability together. Availability replaces the rating line, so the rating is not shown.
- Don't pass a non-text name together with a click handler. The image button takes its label from the name only when it is a string, otherwise it reads Open product.
- Don't format the review count yourself. The card writes it with an English thousands separator, so pass the number 1842 and it reads (1,842).

## API reference

### ProductCard

| Prop | Type | Default | Description |
|---|---|---|---|
| addToCartLabel | React.ReactNode | "Add to cart" | The text of the add-to-cart button. `Add to cart` by default. |
| availability | React.ReactNode |  | A line that replaces the rating, in the success colour, for example `In stock`. With `soldOut` it is the red line and defaults to `Currently unavailable`. |
| badge | { label: React.ReactNode; color?: BadgeColor } |  | A pill on the image: `{ label, color }`. The colour is red by default. |
| className | string |  | Added to the card. Use it for the width. |
| compareAt | React.ReactNode |  | The old price, crossed out beside the price. |
| image | string |  | The address of the product photo. Without it the image area shows the tint and an icon. |
| loading | boolean |  | Shows a skeleton of the card in place of its content: `aria-busy` is set and a visually hidden Loading product is added. `name` and `price` are not needed then. |
| name | React.ReactNode |  | The product name, under the image. Also the label of the button over the image when it is a string. Required unless the card is `loading`. |
| onAddToCart | () => void |  | Adds the add-to-cart button and is called when it is pressed. Leave it out for a product without a quick add. A `soldOut` card never shows the button. |
| onClick | () => void |  | Puts a button over the image and is called when it is pressed. Open the product in the handler. |
| onWishlist | () => void |  | Adds the heart button and is called when it is pressed. |
| price | React.ReactNode |  | The price, a finished string such as `$489.00`. Required unless the card is `loading`. |
| rating | number |  | The rating. Draws the Stars and the number with one decimal. Not shown when `availability` is set. |
| reviews | number |  | The number of reviews, printed in brackets after the rating with a thousands separator in English, such as (1,842). Used only together with `rating`. |
| size | "default" \| "compact" | "default" | `default` is the shop tile. `compact` is a bordered row with a 48 px thumbnail, the name, the price and a round quick-add button (`onAddToCart`), for recommendations and cross-sells. A compact card shows `name`, `price`, `image`, `tint`, `onClick` and `onAddToCart` only, and its placeholder is yellow unless you set `tint`. It replaces ProductMiniCard. |
| soldOut | boolean |  | Marks the product as sold out: a grey Sold out badge replaces `badge`, the availability line turns red (`availability`, `Currently unavailable` by default) and the add-to-cart button is not drawn, also when `onAddToCart` is set. |
| tint | "indigo" \| "blue" \| "purple" \| "pink" \| "red" \| "orange" \| "yellow" \| "green" \| "alternative" |  | The tint of the placeholder: indigo, blue, purple, pink, red, orange, yellow, green or alternative. Indigo by default. Not used with `image`. |
| wishlisted | boolean |  | Fills the heart and sets `aria-pressed`. Controlled: the card does not change it. |

### ProductMiniCard

| Prop | Type | Default |
|---|---|---|
| name* | React.ReactNode |  |
| price* | React.ReactNode |  |
| className | string |  |
| image | string |  |
| onAdd | () => void |  |
| onClick | () => void |  |
| tint | "indigo" \| "blue" \| "purple" \| "pink" \| "red" \| "orange" \| "yellow" \| "green" \| "alternative" | "yellow" |

## Examples

### Content: name and price, rating, availability or a sale price

### Badge: none, sale, new or low stock

### Actions: open, wishlist and add to cart

### State: default, wishlisted, on sale, sold out or loading

### Image: tint, photo or a broken address with its fallback

### Text: short, long and narrow

### Width: 144, 240 and 320 px

### Compact: a row with a thumbnail and a quick-add button

## In context

### Shop grid: filter, save products and fill the cart

The hearts save products and Add to cart fills the count above the grid. The Cable tray is sold out, so it has the grey badge and no button; Filter narrows the grid and Data shows loading cards.

### Wishlist: availability instead of ratings

A saved product shows if it can be bought. The heart removes it from the list, Add all available fills the cart with everything in stock, and a sold out product shows its restock date and no button.

## For AI agents

`get_component("product-card")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
