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

# categories.list

> Listar categorias/coleções da vitrine — alias storefront.collections.list.

# storefront.categories.list(options)

Lista categorias de catálogo (coleções de merchandising) via SDK.

No SDK, `storefront.collections.list()` é **alias** de `storefront.categories.list()`.

No Corvex, **coleção = categoria**. URLs de vitrine usam `/collections/:handle`; no SDK use `categories` (alias `collections`).

## Parâmetros SDK

| Campo | Tipo | Nota | Descrição |
| - | - | - | - |
| `first` | `number` | `limit` | Quantidade (default 20) |
| `parentId` | `string \| null` | `parentId` | Filtrar por pai (`null` = raiz) |
| `includeProducts` | `boolean` | `includeProducts` | Incluir produtos aninhados na resposta |

## Retorno SDK

`Connection<Category>` — ver [Coleção](https://docs-loja.usecorvex.com.br/data/resources/category.md).

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

nodes.map((category) => ({
  id: category.id,
  title: category.title,
  url: category.url,
  imageUrl: category.imageUrl,
  productCount: category.productCount,
}));
```

Cada item é mapeado por `mapCategorySummary`:

| Backend | SDK |
| - | - |
| `name` | `title` (+ alias `name`) |
| `slug` | `handle` |
| `image` (string URL) | `image: Image` + `imageUrl: string` |
| `productCount` | `productCount` |
| `parentId` | `parentId` |

## useCorvexData (canvas do editor)

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

const { data, loading } = useCorvexData('collections', { limit: 8 });
// ou alias legado:
// useCorvexData('categories', { limit: 8 });

const categories = data?.nodes ?? [];
```

Aliases do hook: `collections`, `categories`, `limit` → `first`.

### Normalizar o retorno

O hook legado pode devolver `Connection` ou, em código antigo, array direto. Use sempre:

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
function normalizeCategories(data) {
  if (!data) return [];
  if (Array.isArray(data)) return data;
  if (Array.isArray(data.nodes)) return data.nodes;
  return [];
}
```

Ou o helper do SDK:

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

const categories = unwrapCorvexNodes(data);
```

## Filtrar coleções escolhidas no editor

O picker `collection_list` salva **UUIDs** em `settings.collections`.

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
function resolveCollectionRef(value) {
  if (!value) return null;
  if (typeof value === 'string') return value.trim() || null;
  return value.id || value.handle || value.slug || null;
}

const selectedIds = (settings.collections || [])
  .map(resolveCollectionRef)
  .filter(Boolean);

const { nodes } = await storefront.categories.list({ first: Math.max(20, selectedIds.length) });

const ordered = selectedIds.length
  ? nodes
      .filter((c) => selectedIds.includes(c.id))
      .sort((a, b) => selectedIds.indexOf(a.id) - selectedIds.indexOf(b.id))
  : nodes.slice(0, settings.maxItems ?? 8);
```

## storefront.categories.get(idOrHandle)

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const category = await storefront.categories.get('verao');
// ou UUID
const categoryById = await storefront.categories.get('72a0c0d1-9c0d-41a0-a23c-64099ea04bfd');
```

`getByHandle(handle)` é alias de `get(handle)`.

## useCorvexData — item único

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
useCorvexData('collection', { id: 'uuid-da-categoria' });
// aliases: category, collectionId, handle, slug
```

## Exemplo — defineSectionData

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

export const data = defineSectionData(async ({ storefront, settings }) => ({
  collections: await storefront.categories.list({
    first: settings.maxItems ?? 8,
  }),
}));
```

## Renderizar imagem

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

Ver [Image](https://docs-loja.usecorvex.com.br/data/resources/image.md) e [Erros comuns](https://docs-loja.usecorvex.com.br/data/pitfalls.md).

## Referências

* [Coleção](https://docs-loja.usecorvex.com.br/data/resources/category.md)
* [Section collection-list](https://docs-loja.usecorvex.com.br/data/sections/collection-list.md)
* [products.list](https://docs-loja.usecorvex.com.br/data/queries/products-list.md) (filtrar produtos por categoria)
* [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.