# Product Image

A product photo, or a colored placeholder with an icon when there is no photo yet.

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

## Install

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

## Import

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

## Minimal usage

Then use it:

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

export function Photo() {
  return <ProductImage tint="indigo" className="aspect-[7/4] w-64 rounded-xl" />
}
```

Expected result: You should see a 256 px wide rounded rectangle in the indigo tint with a small package icon in its middle. Add src and alt to show a photo in the same box.

## When to use

### Use Product Image for

- The picture in a product card, a cart line or a recommendation row
- A gallery with a large image and thumbnails
- A tinted placeholder with an icon for products that have no photo yet

### Use something else

- [Avatar](https://wunderui.com/components/avatar) for the picture of a person, with initials as the fallback
- [Product Card](https://wunderui.com/components/product-card) for a whole shop tile that already includes the image
- [Carousel](https://wunderui.com/components/carousel) for several images shown one after another with controls

## Behavior

What the image does with its content, size, source and text. It is display only, so there is no hover, focus or keyboard behaviour.

- **A tile, not a control:** Product Image is a plain span with no role and no focus. To make a thumbnail pressable, wrap it in your own button, as the gallery example does.
- **Photo:** The photo fills the tile and is cropped to fit, never stretched, and a radius on the tile rounds it too. It loads lazily, so set eager loading for the first image above the fold.
- **Placeholder:** Without a source the tile shows the tint and an icon: by default a package icon at a quarter of the tile, 16 to 32 px. A custom icon keeps its own size; give non-Lucide SVGs aria-hidden.
- **Tint and icon with a photo:** The tint and icon belong to the placeholder. When a photo is set they are not used, and the tile has no background behind it.
- **Size and radius:** The tile has no size, ratio or radius, so set them yourself. Without a size a photo takes the full width of its container at its own ratio, and a placeholder collapses around its icon.
- **Loading and errors:** There is no loading state: the photo appears when the browser has it. If the address fails, an error handler is called and the tile falls back to the placeholder until a new source arrives.
- **Alt text:** The alt text is empty by default, so screen readers skip the photo. Pass a description when the image carries information the page does not say elsewhere.
- **Motion and reduced motion:** Nothing is animated: the photo does not fade in and the fallback appears at once, so reduced motion changes nothing.

## Anatomy

- `ProductImage`: A span that centres and clips its content, with no role. It has no size, ratio or radius of its own, so pass all three as a class.
- `Photo`: An image that fills the tile and is cropped to it. It shows when a source is set and has not failed, loads lazily and has an empty alt unless you pass one.
- `Placeholder icon`: The placeholder icon, shown when there is no source or the photo failed to load. It is a package icon by default, a quarter of the tile (16 to 32 px), in the tint's text colour.

## Best practices

### When to use

- Use Product Image for a product picture in a tile, row or gallery, with a placeholder for products without a photo. For a person, use Avatar.

### Do

- Always set a size: a width and a height, or a width and an aspect ratio. The ratio also keeps the page from jumping when the photo arrives.
- Give the image the radius of its box minus the distance to it. In a 16 px box with 8 px padding use a medium radius; an image that touches the edge takes none and lets the box clip it.
- Keep the alt empty when the product name is written next to the image. Pass a description when the image is the only place that shows the product.
- Pass the photo address whenever a product has one, even if it might fail. If it does not load, the tile falls back to the tint and icon by itself; an error handler lets you log the broken address.
- Give a custom icon its own size class, such as size-8. The default icon sizes itself from the tile; yours does not.

### Don't

- Don't treat the placeholder as final content. It holds the place of a photo that does not exist yet.
- Don't expect a loading state or a fade-in. The tile stays empty until the browser has the photo, so reserve the size with a ratio, or show a Skeleton while you fetch the address yourself.
- Don't pass a tint or icon together with a photo and expect to see them. With a photo they are not drawn, so a transparent photo shows the page behind it.

## API reference

### ProductImage

| Prop | Type | Default | Description |
|---|---|---|---|
| alt | string | "" | The text alternative of the photo, an empty string by default, which marks it as decoration. Pass a description when the image carries information. |
| className | string |  | Added to the tile. Use it for the size, the aspect ratio and the radius: the tile has none of its own. |
| icon | React.ReactNode |  | The icon of the placeholder. The package icon by default, sized from the tile. A custom icon keeps its own size, so pass a size class. Not used with `src`. |
| loading | "lazy" \| "eager" | "lazy" | `lazy` (default) or `eager`. Passed to the `img`. Use `eager` for an image that is visible when the page opens. |
| onError | React.ReactEventHandler<HTMLImageElement> |  | Called when the photo fails to load, with the error event of the `img`. The tile has already switched to the tint and the icon; use it to log the address or to report it. |
| src | string |  | The address of the photo. It fills the tile and is cropped to it. Without it the tile shows the placeholder. |
| tint | "indigo" \| "blue" \| "purple" \| "pink" \| "red" \| "orange" \| "yellow" \| "green" \| "alternative" | "yellow" | The tint of the placeholder and of its icon: indigo, blue, purple, pink, red, orange, yellow, green or alternative. Yellow by default. Not used with `src`. |

## Examples

### Content: placeholder, custom icon or photo

### Tint: nine tints for the placeholder

### Shape: ratio, size and radius

### Source: photo, no photo, a broken address or a reported failure

### Alt text: decorative, described or a placeholder

### Corners: concentric to the box around the image

## In context

### Product gallery: thumbnails pick the large image

The thumbnails are buttons and the large image follows the pressed one. With no photos yet, the same gallery shows tinted placeholders.

### Cart lines: a placeholder when the photo is missing or fails

A line with no photo, or with an address that fails, shows its tinted placeholder, so the list never shows an empty box. The name is written next to the image, so the image has no alt text.

## For AI agents

`get_component("product-image")`

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