> ## Documentation Index
> Fetch the complete documentation index at: https://docs-loja.usecorvex.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs-loja.usecorvex.com.br/cookbook/overview.md)

***

## Contratos utilizados

* [Data Contract](https://docs-loja.usecorvex.com.br/reference/contracts/data.md) — `PageContextMap.search`
* [Page Contract](https://docs-loja.usecorvex.com.br/reference/contracts/page.md) — template `search`
* [Product Contract](https://docs-loja.usecorvex.com.br/reference/contracts/product.md) — `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

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
<h1>{searchQuery ? `Busca: “${searchQuery}”` : 'Busca'}</h1>
```

***

## Formulário de busca (GET)

```html theme={"theme":{"light":"github-light","dark":"github-dark"}}
<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):

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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](https://docs-loja.usecorvex.com.br/cookbook/product-card.md) — snippet reutilizado
* [Data Contract](https://docs-loja.usecorvex.com.br/reference/contracts/data.md) — `PageContextMap`
* [Golden Path — search section](https://docs-loja.usecorvex.com.br/guides/create-theme.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.