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

> Section completa com schema, data loader e componente.

# Section: Lista de produtos

Caso de uso: homepage ou landing com produtos filtrados (categoria, destaque, busca, etc.).

## Estrutura

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

## Filtros disponíveis

| Filtro desejado | Setting no `schema.json` | Parâmetro SDK | Nota |
| - | - | - | - |
| Uma categoria | `{ "type": "collection", "id": "collection" }` | `collection` / `collectionId` | `categoryId` |
| Várias categorias (OR) | `{ "type": "collection_list", "id": "collections", "max": 10 }` | `categories: string[]` | `categories` (CSV) |
| Busca por nome | `{ "type": "text", "id": "query" }` | `query` | `search` |
| Só destaques | `{ "type": "checkbox", "id": "featured" }` | `featured: true` | `featured=true` |
| Só com estoque | `{ "type": "checkbox", "id": "availableOnly" }` | `inStock: true` | `inStock=true` |
| Quantidade | `{ "type": "range", "id": "limit" }` | `first` / `limit` | `limit` |
| Ordenação | `{ "type": "select", "id": "sortBy" }` | `sortBy` | `sortBy` + `sortOrder` |
| Ordem reversa | `{ "type": "checkbox", "id": "reverse" }` | `reverse` | `sortOrder` |
| Faixa de preço | `{ "type": "number", "id": "minPrice" }` etc. | `minPrice` / `maxPrice` | idem |

> **Coleção = categoria** no SDK Corvex. Ver [Coleção](https://docs-loja.usecorvex.com.br/data/resources/category.md).

Deixe `collection` vazio para listar **todos** os produtos da loja.

## 1. Schema (picker de categoria)

Use `type: "collection_list"` para **várias** categorias (OR no backend). Uma só: `type: "collection"`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "collection",
  "id": "collection",
  "label": "Filtrar por categoria/coleção",
  "info": "Vazio = todos os produtos"
}
```

O editor abre o seletor de coleção e salva o UUID da categoria.

## 2. Data loader (`defineSectionData`)

Padrão recomendado para preview/loja publicada:

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

export const data = defineSectionData(async ({ storefront, settings }) => ({
  products: await storefront.products.list({
    first: settings.limit ?? 8,
    collection: settings.collection || undefined,
    query: settings.query || undefined,
    featured: settings.featured || undefined,
    sortBy: settings.sortBy ?? 'BEST_SELLING',
    reverse: settings.reverse || undefined,
    inStock: settings.availableOnly ? true : undefined,
  }),
}));
```

## 3. Alternativa: `useCorvexData` (canvas do editor)

Sections de agência/tema customizado podem buscar no componente:

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

function resolveCollectionRef(value) {
  if (!value) return null;
  if (typeof value === 'string') return value.trim() || null;
  return value.id || value.handle || null;
}

export default function ProductListSection({ collection = '', limit = 8, sortBy = 'BEST_SELLING', featured = false }) {
  const categoryId = resolveCollectionRef(collection);

  const { data, loading } = useCorvexData('products', {
    limit,
    sortBy,
    ...(categoryId && { collectionId: categoryId }),
    ...(featured && { featured: true }),
  });

  const products = data?.nodes ?? [];
  // ...
}
```

`useCorvexData` aceita aliases legados: `collectionId`, `categoryId`, `limit`, `query`, `featured`, `reverse`.

## 4. Componente

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import ProductCard from '@corvex/snippets/product-card';

export default function ProductList({ settings, data }) {
  const products = data?.products?.nodes ?? [];

  if (!products.length) {
    return <p>Nenhum produto nesta coleção.</p>;
  }

  return (
    <section className="product-list">
      <h2>{settings.title}</h2>
      <div className="product-list__grid">
        {products.map((product) => (
          <ProductCard key={product.id} product={product} />
        ))}
      </div>
    </section>
  );
}
```

## Fluxo completo

```
Lojista escolhe categoria "Games" no inspector
        ↓
settings.collection = "uuid-da-categoria"
        ↓
storefront.products.list({ collection: "uuid..." })
        ↓
GET /products?categoryId=uuid...
        ↓
Connection<Product> → section renderiza cards
```

## Filtro interativo (visitante)

Configurar categoria no editor ≠ abas/chips na loja para o cliente trocar filtro. Para isso:

1. `useCorvexData('collections', { limit: 100 })` — lista categorias
2. `useState` com a categoria selecionada
3. Nova busca `useCorvexData('products', { collectionId: selectedId })`

Esse padrão ainda não tem página dedicada — implemente na section conforme UX desejada.

## Referências

* [products.list](https://docs-loja.usecorvex.com.br/data/queries/products-list.md)
* [Product](https://docs-loja.usecorvex.com.br/data/resources/product.md)
* [Coleção](https://docs-loja.usecorvex.com.br/data/resources/category.md)
* [Regras de escopo](https://docs-loja.usecorvex.com.br/data/scope-rules.md)


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