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)

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

1. Data loader (recomendado)

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.

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

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 com setting collection ou collection_list — o SDK envia categoryId / categories ao backend de produtos.

Referências

• categories.list
• Coleção
• Image
• Erros comuns