---
title: "ProductCard"
description: "A product tile with image, linked title, optional rating, price, points and badges. The rating is formatted through the provider."
kind: block
id: C-045
category: storefront
registry: "product-card"
docs: "https://koten.codehive.com.co/blocks/storefront/product-card"
markdown: "https://koten.codehive.com.co/md/blocks/storefront/product-card.md"
install: "npx shadcn@latest add https://koten.codehive.com.co/r/product-card.json"
language: en
---

# ProductCard · 商品カード

> Block C-045 in the Koten UI catalog.

A product tile with image, linked title, optional rating, price, points and badges. The rating is formatted through the provider.

> Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031).

## Install

Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project.

```bash
# Node
npx shadcn@latest add https://koten.codehive.com.co/r/product-card.json

# Bun
bunx shadcn@latest add https://koten.codehive.com.co/r/product-card.json
```

## Files

- `@/components/patterns/product-card.tsx`
- `@/lib/koten/cn.ts`
- `@/lib/koten/format.ts`
- `@/lib/koten/intl.ts`
- `@/lib/koten/labels.ts`
- `@/lib/koten/provider.tsx`

## Requirements

- **provider** — KotenProvider for the rating: The rating value and review count are formatted with useKotenFormatters. Wrap the page in KotenProvider so separators and language match the rest of the store.

## Composition

This block composes Koten primitives. Read the source files above before changing its anatomy.

## Examples

### Plain card and rated card

Badges sit over the image; the rating pairs decorative stars with the real number.

```tsx
<ProductCard
  href="/products/35mm"
  title="HIKARI 35mm f/2.8"
  image={{ src: "/images/35mm.jpg", alt: "HIKARI 35 mm lens" }}
  price="¥32,400"
  points="324 points"
  meta="Prime lens"
/>

<ProductCard
  href="/products/k-1-silver"
  title="HIKARI K-1 silver"
  image={{ src: "/images/k-1.jpg", alt: "HIKARI K-1 camera in silver" }}
  price="¥58,300"
  points="583 points"
  meta="Limited colour"
  badges={<Badge tone="sale" appearance="solid">Limited</Badge>}
  rating={{ value: 4.6, count: 128, label: "reviews" }}
/>
```

## Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `href` | `string` | `—` | Destination of the title; the whole card is not a link, to avoid nested interactive elements. |
| `title` | `ReactNode` | `—` | Visible name and the card's real link. |
| `image` | `{ src: string; alt: string; width?: number; height?: number }` | `400 × 300` | The image keeps a 4:3 ratio; alt describes the product, not the file. |
| `price` | `ReactNode` | `—` | Main price; uses tabular figures and the theme primary colour. |
| `points` | `ReactNode` | `—` | Optional loyalty points, always with the unit written out. |
| `badges` | `ReactNode` | `—` | Overlaid on the image at the start corner. |
| `rating` | `{ value: number; count: number; label: string }` | `—` | Decorative stars plus value and count formatted by the provider. |

## Accessibility

- The card is an <article> and the title is the only link, with a visible focus ring.
- The rating shows the number and unit as text; stars are aria-hidden.
- Badges add words, not just colour, and never cover the image's alternative text.
- The image alt describes the product; if the image is decorative, the card must still make sense without it.

## Sources

- Catalog page: https://koten.codehive.com.co/blocks/storefront/product-card
- Markdown: https://koten.codehive.com.co/md/blocks/storefront/product-card.md
- Repository: https://github.com/codehive-colombia/koten