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

# Exemplo — Lista de coleções

> Section completa com schema, fetch de categorias e renderização de imagens.

# Section: Lista de coleções

Caso de uso: homepage com grid ou carrossel de coleções (categorias de catálogo).

## Estrutura

```
sections/collection-list/
├── schema.json
├── section.jsx
└── styles.css
```

## Schema (picker de coleções)

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "collection_list",
  "id": "collections",
  "label": "Coleções",
  "max": 8,
  "info": "Vazio = exibe automaticamente as primeiras coleções da loja."
}
```

| Setting | Tipo | Valor salvo |
| - | - | - |
| `collection_list` | picker | `string[]` de UUIDs |
| `range` `maxItems` | número | limite quando lista vazia |
| `textarea` `imageOverridesJson` | JSON | `{ "uuid": "https://..." }` opcional |

Ver todos os tipos em [Schema de section](https://docs-loja.usecorvex.com.br/sections/schema.md).

## 1. Data loader (recomendado)

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

export const data = defineSectionData(async ({ storefront, settings }) => {
  const ids = Array.isArray(settings.collections) ? settings.collections : [];
  const limit = settings.maxItems ?? 8;
  const collections = await storefront.categories.list({
    first: Math.max(limit, ids.length || limit),
  });
  const nodes = ids.length
    ? collections.nodes.filter((category) => ids.includes(category.id))
    : collections.nodes.slice(0, limit);

  return { collections: { ...collections, nodes } };
});
```

`categories.list` não aceita lista de ids. A section pede uma página grande o bastante e filtra no cliente. Um UUID que não veio nessa página não aparece.

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

function resolveCollectionRefs(collections) {
  if (!collections) return [];
  const entries = Array.isArray(collections) ? collections : [collections];
  return [...new Set(
    entries
      .map((value) => {
        if (typeof value === 'string') return value.trim() || null;
        return value?.id || value?.handle || value?.slug || null;
      })
      .filter(Boolean)
  )];
}

function normalizeCategories(data) {
  if (!data) return [];
  if (Array.isArray(data)) return data;
  if (Array.isArray(data.nodes)) return data.nodes;
  return [];
}

function resolveCategoryImageUrl(category) {
  if (!category) return '';
  if (typeof category.imageUrl === 'string' && category.imageUrl) {
    return category.imageUrl;
  }
  const image = category.image;
  if (typeof image === 'string' && image) return image;
  if (image?.url) return image.url;
  return '';
}

export default function CollectionListSection({
  collections = [],
  maxItems = 8,
}) {
  const selectedIds = resolveCollectionRefs(collections);
  const fetchLimit = Math.max(maxItems, selectedIds.length || maxItems, 8);

  const { data, loading } = useCorvexData('collections', { limit: fetchLimit });
  const raw = normalizeCategories(data);

  const items = (selectedIds.length
    ? raw.filter((c) => selectedIds.includes(c.id))
    : raw.slice(0, maxItems)
  ).map((category) => ({
    id: category.id,
    title: category.title || category.name,
    url: category.url || `/collections/${category.handle || category.slug}`,
    imageUrl: resolveCategoryImageUrl(category),
  }));

  if (loading) return <p>Carregando coleções…</p>;
  if (!items.length) return <p>Nenhuma coleção encontrada.</p>;

  return (
    <section className="collection-list">
      <div className="collection-list__grid">
        {items.map((item) => (
          <a key={item.id} href={item.url} className="collection-list__item">
            {item.imageUrl ? (
              <img src={item.imageUrl} alt={item.title} loading="lazy" />
            ) : (
              <div className="collection-list__placeholder" aria-hidden="true" />
            )}
            <span>{item.title}</span>
          </a>
        ))}
      </div>
    </section>
  );
}
```

## 3. Componente com `data` injetado

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
export default function CollectionList({ settings, data }) {
  const categories = data?.collections?.nodes ?? [];

  return (
    <section>
      <h2>{settings.title}</h2>
      <div className="collection-list__grid">
        {categories.map((category) => (
          <a key={category.id} href={category.url}>
            <img
              src={category.imageUrl || category.image?.url}
              alt={category.title}
            />
            <span>{category.title}</span>
          </a>
        ))}
      </div>
    </section>
  );
}
```

## Fluxo completo

```
Lojista escolhe coleções no inspector (collection_list)
        ↓
settings.collections = ["uuid-1", "uuid-2", ...]
        ↓
storefront.categories.list({ first: N })
        ↓
GET /categories?limit=N
        ↓
Connection<Category> → filtra/ordena por UUID → renderiza cards
```

## Ligação com lista de produtos

Para mostrar **produtos de uma coleção**, use [product-list](https://docs-loja.usecorvex.com.br/data/sections/product-list.md) com setting `collection` ou `collection_list` — o SDK envia `categoryId` / `categories` ao backend de produtos.

## Referências

* [categories.list](https://docs-loja.usecorvex.com.br/data/queries/categories-list.md)
* [Coleção](https://docs-loja.usecorvex.com.br/data/resources/category.md)
* [Image](https://docs-loja.usecorvex.com.br/data/resources/image.md)
* [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.