Criar Product Grid

Golden Path — Section de grid de produtos com collection, data loaders e carrinho.

Card montável no editor (imagem, título, preço por bloco, repetido em cada produto): use o cookbook Grade com blocos de catálogo. Este guia cobre grade + dados; o cookbook cobre section, blocks e persistência.

Golden Path para uma section de produtos orientada a dados — o principal exemplo de Section que lista catálogo na Corvex.

Contratos: Section · Data · Product · Cart · Schema.

---

1. Section mínima

File: sections/product-grid/schema.json

{
  "type": "product-grid",
  "name": "Grid de produtos",
  "category": "Produtos",
  "settings": []
}

File: sections/product-grid/section.jsx

export default function ProductGridSection() {
  return (
    <section className="product-grid">
      <p>Grid de produtos</p>
    </section>
  );
}

theme.json → "sections": [ "product-grid", … ]

---

2. Schema completo

{
  "type": "product-grid",
  "name": "Grid de produtos",
  "category": "Produtos",
  "data": ["products"],
  "settings": [
    {
      "id": "title",
      "type": "text",
      "label": "Título",
      "default": "Nossos produtos"
    },
    {
      "id": "subtitle",
      "type": "textarea",
      "label": "Subtítulo"
    },
    {
      "id": "limit",
      "type": "range",
      "label": "Quantidade",
      "min": 1,
      "max": 24,
      "step": 1,
      "default": 8
    },
    {
      "id": "collection",
      "type": "collection",
      "label": "Coleção (opcional)"
    }
  ]
}

Field	Tipo estável	Função
title	text	Título da section
subtitle	textarea	Texto de suporte
limit	range	Máximo de produtos
collection	collection	Filtrar por coleção (UUID)

---

3. Título e subtítulo

export default function ProductGridSection({ settings = {} }) {
  return (
    <section style={{ padding: '48px 24px', maxWidth: 1200, margin: '0 auto' }}>
      <h2 style={{ margin: '0 0 8px' }}>
        {settings.title || 'Nossos produtos'}
      </h2>
      {settings.subtitle && (
        <p style={{ margin: '0 0 24px', opacity: 0.8 }}>
          {settings.subtitle}
        </p>
      )}
    </section>
  );
}

---

4. Quantidade (range)

settings.limit é number. Use no fetch:

const limit = settings.limit ?? 8;

---

5. Seleção de Collection

Quando settings.collection tem UUID, filtre a listagem:

await storefront.products.list({
  first: limit,
  collection: settings.collection,
});

Sem coleção selecionada: listagem geral (sem filtro de categoria).

---

6. schema.data: ["products"]

sections/product-grid/schema.json é o arquivo que corvex validate lê. O build copia esse JSON para o componente só se o componente ainda não tiver .schema.

Declare data nesse arquivo. Não duplique o schema com defineSection no JSX: se o componente já tiver .schema, o build deixa de anexar o schema.json e o inspetor pode divergir do arquivo validado.

---

7. defineSectionData

data: ["products"] no schema.json já lista com settings.limit (ou settings.first, padrão 8), settings.collection, settings.category, settings.featured e settings.sortBy.

Use defineSectionData quando a consulta não cabe nessa chave. A runtime lê a função em Componente.data, não o export solto:

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

export const data = defineSectionData(async ({ storefront, settings }) => {
  const limit = settings.limit ?? 8;
  const options = { first: limit };

  if (settings.collection) {
    options.collection = settings.collection;
  }

  return {
    products: await storefront.products.list(options),
  };
});

Depois do loader, atribua ProductGridSection.data = data. Sem isso, a chave products do schema é que roda.

---

8. Product Contract

Produtos chegam em data.products.nodes (Connection<Product>):

const products = data?.products?.nodes ?? [];

Campos garantidos em cards: id, title, url, featuredImage, price, compareAtPrice, availableForSale.

Product Contract

---

9. ProductVariant

Para grid de cards, variante não é obrigatória — use product.availableForSale e addItem(product) quando não há seletor.

PDP usa variantes — ver Product Variant.

---

10. ProductCard (snippet scaffold)

import ProductCard from '@corvex/snippets/product-card';

{products.map((product) => (
  <ProductCard key={product.id} product={product} />
))}

O scaffold oficial inclui snippets/product-card/snippet.jsx. Card usa product.title, product.featuredImage, product.price.formatted.

Componente ProductCard do SDK (@corvex/theme-sdk) é alternativa pública documentada no SDK overview.

---

11. Imagem

const img = product.featuredImage;
if (img?.url) {
  return (
    <img
      src={img.url}
      alt={img.altText || product.title}
      loading="lazy"
      style={{ width: '100%', aspectRatio: '1', objectFit: 'cover' }}
    />
  );
}

---

12. Preço

<span>{product.price.formatted}</span>

O starter traz snippets/product-card. Não há snippet product-price nesse tema.

---

13. Compare-at price

Parte do contrato ProductSummary:

{product.compareAtPrice && (
  <s>{product.compareAtPrice.formatted}</s>
)}

---

14. Variante e add to cart

Grid simples — adicionar produto sem variante explícita quando única variante:

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

function ProductGridCard({ product }) {
  const { addItem, mutating } = useCorvexCart();

  return (
    <article>
      <ProductCard product={product} />
      <button
        type="button"
        disabled={!product.availableForSale || mutating}
        onClick={() => addItem(product, 1)}
      >
        Adicionar
      </button>
    </article>
  );
}

Com múltiplas variantes, link para product.url em vez de add direto.

Cart Contract

---

15. Loading

Com defineSectionData ou schema.data, a vitrine não monta a seção enquanto a carga não termina e ainda não há data. O componente não recebe essa espera: um if (!data) dentro dele não é a tela de carregamento.

useCorvexData('products', params) busca no próprio componente. Aí o estado de espera fica no retorno do hook.

---

16. Empty state

if (!products?.length) {
  return (
    <section style={{ padding: '48px 24px', maxWidth: 1200, margin: '0 auto' }}>
      <h2>{settings.title || 'Nossos produtos'}</h2>
      <p style={{ opacity: 0.7 }}>Nenhum produto encontrado.</p>
    </section>
  );
}

---

17. Responsividade

<div
  style={{
    display: 'grid',
    gridTemplateColumns: 'repeat(auto-fill, minmax(220px, 1fr))',
    gap: 24,
  }}
>
  …
</div>

CSS opcional em sections/product-grid/styles.css.

---

18. Performance

• Use limit em products.list({ first: limit }) — não renderize o catálogo inteiro.
• Use loading="lazy" em imagens de card.
• Evite buscar produto individual em loop (N+1) — use os dados da listagem.

---

19. Editor

• Inspector mostra fields do schema.json.
• Picker collection salva UUID.
• O canvas lê o estado aberto no editor (Preview Contract).
• Pré-visualizar grava o rascunho da página antes de abrir a aba.

---

20. Section completa

File: sections/product-grid/section.jsx

O schema.json da seção 2 continua obrigatório. Este arquivo não declara schema de novo.

import { defineSectionData, useCorvexCart } from '@corvex/theme-sdk';
import ProductCard from '@corvex/snippets/product-card';

export const data = defineSectionData(async ({ storefront, settings }) => {
  const limit = settings.limit ?? 8;
  const options = { first: limit };
  if (settings.collection) {
    options.collection = settings.collection;
  }
  return { products: await storefront.products.list(options) };
});

function GridCard({ product }) {
  const { addItem, mutating } = useCorvexCart();
  return (
    <div>
      <ProductCard product={product} />
      <button
        type="button"
        disabled={!product.availableForSale || mutating}
        onClick={() => addItem(product, 1)}
        style={{ marginTop: 8, width: '100%' }}
      >
        Adicionar
      </button>
    </div>
  );
}

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

  return (
    <section
      className="product-grid"
      style={{ padding: '48px 24px', maxWidth: 1200, margin: '0 auto' }}
    >
      <h2 style={{ margin: '0 0 8px' }}>
        {settings.title || 'Nossos produtos'}
      </h2>
      {settings.subtitle && (
        <p style={{ margin: '0 0 24px', opacity: 0.8 }}>{settings.subtitle}</p>
      )}

      {products.length === 0 ? (
        <p style={{ opacity: 0.7 }}>Nenhum produto encontrado.</p>
      ) : (
        <div
          style={{
            display: 'grid',
            gridTemplateColumns: 'repeat(auto-fill, minmax(220px, 1fr))',
            gap: 24,
          }}
        >
          {products.map((product) => (
            <GridCard key={product.id} product={product} />
          ))}
        </div>
      )}
    </section>
  );
}

ProductGridSection.data = data;

export default ProductGridSection;

A runtime lê ProductGridSection.data. O export nomeado sozinho não chega ao componente. Não atribua ProductGridSection.schema: o build já anexa o schema.json quando essa propriedade está vazia.

Registrar em theme.json e adicionar à home em templates/index.json se desejar.

---

Checklist

• schema.json com name, category
• data: ['products'] ou defineSectionData
• Field types estáveis apenas
• collection opcional no list options
• Empty state
• limit no fetch
• Product fields só do Product Contract
• useCorvexCart().addItem para CTA
• corvex validate + corvex build

---

Veja também

• Criar Theme completo
• Coleção
• Schema: collection field
• Product Card Cookbook
• Variant Selector Cookbook
• Cookbooks — índice