Search Results

Cookbook — página de busca com usePage(‘search’), grid de Product Card e formulário GET.

Quero exibir resultados na página /search?q=…. Como implementar?

Referência: seu tema (adaptado do cookbook)

Índice: Cookbooks

---

Contratos utilizados

• Data Contract — PageContextMap.search
• Page Contract — template search
• Product Contract — ProductSummary nos cards
• @corvex/theme-sdk — usePage('search')
• @corvex/runtime — SectionChrome
• Snippet reutilizado: @corvex/snippets/product-card

---

API pública de busca

Fonte	Uso
usePage('search')	No template search, o contexto traz searchQuery e results. O argumento do hook não escolhe a página
storefront.search.query({ query })	Busca manual em defineSectionData (não necessário neste cookbook)
schema.data: ['search']	Declara dependência — runtime injeta page.results

Query string: ?q= ou ?query= (resolvido pela plataforma em resolvePageContext).

Rota: /search ou /busca → PageType search.

---

Fluxo de dados

URL /search?q=camiseta
        ↓
Runtime resolve page context
        ↓
usePage('search') → { searchQuery, results: { nodes } }
        ↓
Grid de ProductCard (snippet)

Não chame storefront.search.query na section se o contexto de página já fornece results — evita dupla requisição.

---

Section (padrão canônico)

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

const { searchQuery, results } = usePage('search');
const nodes = results?.nodes ?? [];

Título com query:

<h1>{searchQuery ? `Busca: “${searchQuery}”` : 'Busca'}</h1>

---

Formulário de busca (GET)

<form action="/search" method="get" role="search">
  <input name="q" type="search" defaultValue={searchQuery || ''} />
</form>

Submit nativo — sem JavaScript obrigatório. Parâmetro canônico: q.

---

Schema

Setting	Uso
titlePrefix	Prefixo do <h1>
emptyText	Sem resultados
showSearchForm	Exibir formulário GET
searchPlaceholder	Placeholder do input
showSaleBadge	Badge nos Product Cards
columns	Colunas do grid (desktop)

enabledOn: ['search'] · data: ['search']

---

Template obrigatório

templates/search.json MUST referenciar esta section (ou equivalente):

{
  "type": "search",
  "sections": {
    "main": { "type": "search-results", "settings": {} }
  },
  "order": ["main"]
}

---

Edge cases

Caso	UI
Sem q na URL	Título sem query; results vazio
results.nodes vazio	emptyText
results null	Tratar como [] (results?.nodes ?? [])
Editor (isEditing)	Input readOnly para evitar navegação acidental

---

Separação com Product Card

• Search Results — contexto de página, produtos da busca
• Product Card — product_list manual no inspector (storefront.products.get)

Não misturar resolução: busca usa usePage; grid manual usa defineSectionData.

---

Checklist

• usePage('search') — não storefront.search duplicado
• results?.nodes com fallback []
• Product Card snippet para UI
• Template search.json no tema
• corvex validate .

---

Veja também

• Product Card — snippet reutilizado
• Data Contract — PageContextMap
• Golden Path — search section