> ## 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.

# Coleção

> Categorias de catálogo — categories no SDK, alias collections, URLs /collections/:handle.

No SDK, `storefront.collections` é **alias** de `storefront.categories`. Use `storefront.categories.list()` / `.get()` / `.getByHandle()`.

**Coleção = categoria.** URLs de vitrine são `/collections/:handle`, mas os métodos do SDK usam o namespace `categories` (com alias `collections`). Ver [Erros comuns](https://docs-loja.usecorvex.com.br/data/pitfalls.md).

## Campos (SDK)

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | `string` | UUID |
| `handle` | `string` | Slug (`verao`, `camisetas`) |
| `url` | `string` | `/collections/:handle` |
| `title` | `string` | Nome exibido |
| `name` | `string` | Alias de `title` |
| `description` | `string \| null` | Descrição |
| `image` | `Image \| null` | Objeto normalizado |
| `imageUrl` | `string \| null` | URL pronta para `<img src>` |
| `productCount` | `number` | Total de produtos |
| `parentId` | `string \| null` | Hierarquia |

## Imagem — payload bruto vs SDK

A origem pode devolver `image` como **string URL**:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "72a0c0d1-...",
  "name": "VERAO",
  "slug": "verao",
  "image": "https://cdn.example.com/collections/verao.png"
}
```

O SDK (`mapCategorySummary`), quando o backend manda `image` como string, grava:

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  image: {
    id: "https://cdn.example.com/collections/verao.png",
    url: "https://cdn.example.com/collections/verao.png",
    altText: "VERAO",
    width: null,
    height: null,
  },
  imageUrl: "https://cdn.example.com/collections/verao.png",
}
```

`id` vira a própria URL. `altText` vira o título da categoria.

### Renderizar no tema

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
function CollectionCard({ category }) {
  const src = category.imageUrl || category.image?.url;
  const alt = category.image?.altText || category.title;

  return (
    <a href={category.url}>
      {src ? <img src={src} alt={alt} loading="lazy" /> : <div className="placeholder" />}
      <span>{category.title}</span>
    </a>
  );
}
```

Nunca use `<img src={category.image} />` — `image` é objeto após o SDK, não string.

## Mapeamento backend → SDK

| Backend | SDK |
| - | - |
| `name` | `title`, `name` |
| `slug` | `handle` |
| `image` (string) | `image` (`Image`) + `imageUrl` |
| `productCount` | `productCount` |
| `parentId` | `parentId` |
| `description` | `description` |

## Buscar lista

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const { nodes } = await storefront.categories.list({ first: 20 });
// alias: storefront.collections.list()
```

Com hook no editor:

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const { data, loading } = useCorvexData('collections', { limit: 20 });
const categories = data?.nodes ?? [];
```

Documentação completa: [categories.list](https://docs-loja.usecorvex.com.br/data/queries/categories-list.md).

## Buscar uma coleção

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const category = await storefront.categories.get('verao');
// ou por UUID
```

## Setting no editor

O picker `type: "collection"` salva o **UUID** da categoria:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "collection": "b41aa0fc-3458-4b0e-a136-c48bb0c32c6c"
}
```

Lista manual (`collection_list`):

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "collections": ["uuid-1", "uuid-2"]
}
```

Na query de **produtos**, passe em `collection` ou `category` — o SDK envia `categoryId` ao backend.

Deixe vazio para **não filtrar** por categoria.

## Contexto de template collection

Em `/collections/:handle`, a plataforma injeta:

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

const { collection, products } = usePage('collection');
```

Ver [Contexto de página](https://docs-loja.usecorvex.com.br/data/page-context.md).

## Exemplo — grid na home

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

export default function CollectionGrid({ limit = 6 }) {
  const { data, loading } = useCorvexData('collections', { limit });

  if (loading) return null;

  return (
    <div className="collection-grid">
      {(data?.nodes ?? []).map((category) => (
        <a key={category.id} href={category.url}>
          <img src={category.imageUrl} alt={category.title} />
          <span>{category.title}</span>
        </a>
      ))}
    </div>
  );
}
```

Section de referência: [collection-list](https://docs-loja.usecorvex.com.br/data/sections/collection-list.md).

## Tipos relacionados

* [Image](https://docs-loja.usecorvex.com.br/data/resources/image.md)
* [Product](https://docs-loja.usecorvex.com.br/data/resources/product.md) (filtro por `collection`)
* [Erros comuns](https://docs-loja.usecorvex.com.br/data/pitfalls.md)


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