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.

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:

{
  "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:

{
  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

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

const { nodes } = await storefront.categories.list({ first: 20 });
// alias: storefront.collections.list()

Com hook no editor:

const { data, loading } = useCorvexData('collections', { limit: 20 });
const categories = data?.nodes ?? [];

Documentação completa: categories.list.

Buscar uma coleção

const category = await storefront.categories.get('verao');
// ou por UUID

Setting no editor

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

{
  "collection": "b41aa0fc-3458-4b0e-a136-c48bb0c32c6c"
}

Lista manual (collection_list):

{
  "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:

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

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

Ver Contexto de página.

Exemplo — grid na home

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.

Tipos relacionados

• Image
• Product (filtro por collection)
• Erros comuns