> ## Documentation Index
> Fetch the complete documentation index at: https://docs-loja.usecorvex.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Image

> Tipo primitivo de imagem na Storefront Data API.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
interface Image {
  id: string;
  url: string;
  altText: string | null;
  width: number | null;
  height: number | null;
}
```

O SDK expõe imagens como **objeto `Image`**. Alguns recursos também expõem **`imageUrl`** (string) para uso direto em `<img src>`.

| Recurso | Campo objeto | Campo string |
| - | - | - |
| Product | `featuredImage` | use `featuredImage?.url` ou `getProductImage()` |
| Product (galeria) | `images[]` | `images[n].url` |
| ProductVariant | `image` | `image?.url` |
| Coleção | `image` | `imageUrl` |

***

## Produto

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
<img
  src={product.featuredImage?.url}
  alt={product.featuredImage?.altText || product.title}
  width={product.featuredImage?.width || undefined}
  height={product.featuredImage?.height || undefined}
/>
```

### Helper

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { getProductImage } from '@corvex/theme-sdk';

const url = getProductImage(product);
if (url) {
  return <img src={url} alt={product.title} />;
}
```

`getProductImage` tenta, em ordem: `featuredImage.url`, `images[0]`, `imageUrl`, `image` (string ou objeto), variante, `media.images`.

***

## Categoria / coleção

Backend envia `image` como **string URL**. O SDK normaliza para `Image` + `imageUrl`.

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
// ✅ Preferido
<img src={category.imageUrl || category.image?.url} alt={category.title} />

// ❌ Errado — image é objeto
<img src={category.image} alt={category.title} />
```

Ver [Coleção](https://docs-loja.usecorvex.com.br/data/resources/category.md) e [Erros comuns](https://docs-loja.usecorvex.com.br/data/pitfalls.md).

***

## Componente SDK

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Image } from '@corvex/theme-sdk';

<Image src={product.featuredImage?.url} alt={product.title} />
```

***

## Settings `type: "image"` no schema

O inspector salva **URL string** diretamente na prop da section (ex.: `imageUrl`, `backgroundImage`). Não passa pelo mapper `Image` — use como string:

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
<section style={{ backgroundImage: `url(${settings.imageUrl})` }} />
```

***

## Checklist

* [ ] `src` sempre recebe **string URL**, nunca objeto `Image`
* [ ] Categorias: `imageUrl` ou `image?.url`
* [ ] Produtos: `featuredImage?.url` ou `getProductImage(product)`
* [ ] `alt` com fallback para `title` / `name`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.