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.

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)

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:

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:

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.

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)

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

useCorvexData('collection', { id: 'uuid-da-categoria' });
// aliases: category, collectionId, handle, slug

Exemplo — defineSectionData

import { defineSectionData } from '@corvex/theme-sdk';

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

Renderizar imagem

<img
  src={category.imageUrl || category.image?.url || ''}
  alt={category.image?.altText || category.title}
  loading="lazy"
/>

Ver Image e Erros comuns.

Referências

• Coleção
• Section collection-list
• products.list (filtrar produtos por categoria)
• Erros comuns