> ## 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.

# Header

> Cookbook — header com menu, color scheme, layout group e carrinho.

> Quero um header com logo, menu publicado e carrinho. Qual é a implementação recomendada?

Código de referência validado: `seu tema (adaptado do cookbook)`

Índice: [Cookbooks](https://docs-loja.usecorvex.com.br/cookbook/overview.md)

***

## Contratos utilizados

* [Section Contract](https://docs-loja.usecorvex.com.br/reference/contracts/section.md)
* [Schema Contract](https://docs-loja.usecorvex.com.br/reference/contracts/schema.md)
* [Theme Contract](https://docs-loja.usecorvex.com.br/reference/contracts/theme.md) — `layoutGroups`
* Field [`menu`](https://docs-loja.usecorvex.com.br/schema/fields/menu) — valor persistido = **handle**
* Field [`color_scheme`](https://docs-loja.usecorvex.com.br/schema/fields/color-scheme) — valor persistido = **scheme id**
* Field [`image`](https://docs-loja.usecorvex.com.br/schema/fields/image) — logo opcional
* [Cart Contract](https://docs-loja.usecorvex.com.br/reference/contracts/cart.md) — `useCorvexCart()`
* [Data — menus](https://docs-loja.usecorvex.com.br/data/menus-blog.md)

***

## Objetivo

Header global com:

* logo (texto ou imagem)
* menu resolvido via handle (`settings.menu`)
* link do carrinho com contagem
* esquema de cores aplicado ao subtree
* menu mobile simples (toggle, sem mega menu)

O header entra via **layout group** — não duplique em cada template.

***

## Arquivos

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
sections/cookbook-header/
├── section.jsx
├── schema.json
└── styles.css

groups/header.json          # defaults do layout group
theme.json                  # layoutGroups.header → cookbook-header
config/settings.schema.json # color_schemes para color_scheme field
```

***

## Schema

`settings.menu` persiste o **handle** (ex.: `"main"`), não o objeto do menu.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "menu",
  "type": "menu",
  "label": "Menu principal",
  "default": "main"
}
```

Ver referência completa: [`menu`](https://docs-loja.usecorvex.com.br/schema/fields/menu).

***

## Resolver o menu (handle → links)

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { useStorefrontMenus, StorefrontNav } from '@corvex/runtime';

const menuHandle = settings.menu || 'main';
const { getMenu, loading } = useStorefrontMenus([menuHandle]);
const menu = getMenu(menuHandle);

<StorefrontNav
  menu={menu}
  emptyFallback={<span>{loading ? 'Carregando…' : 'Menu não publicado'}</span>}
/>
```

`menu` é o objeto público (`items`, `label`, `handle`) retornado pelo SDK após resolver o handle.

***

## Color scheme na section

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { ColorSchemeScope, useThemeSettingsReader } from '@corvex/runtime';

const { settings: themeSettings, schema: themeSettingsSchema } =
  useThemeSettingsReader();

<ColorSchemeScope
  as="header"
  colorSchemeId={settings.colorScheme}
  themeSettings={themeSettings}
  themeSettingsSchema={themeSettingsSchema}
  style={{
    background: 'var(--color-background, #fff)',
    color: 'var(--color-text, #111827)',
  }}
>
  …
</ColorSchemeScope>
```

`settings.colorScheme` é o **id** do esquema (ex.: `scheme-light`), não o objeto de cores.

***

## Layout group (global)

`theme.json`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
"layoutGroups": {
  "header": {
    "name": "Cabeçalho",
    "position": "before",
    "sections": ["cookbook-header"]
  }
}
```

`groups/header.json` define a instância padrão (menu `main`, logo, etc.). Ver [Theme Contract](https://docs-loja.usecorvex.com.br/reference/contracts/theme.md).

***

## Carrinho

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { useCorvexCart } from '@corvex/runtime';

const { itemCount } = useCorvexCart();

<a href="/cart">Carrinho ({itemCount})</a>
```

`itemCount` vem de `useCorvexCart`, o mesmo hook do [drawer](https://docs-loja.usecorvex.com.br/cookbook/cart-drawer.md). Os dois leem o carrinho publicado pelo `CorvexCartProvider`. Este exemplo não abre o drawer. O link vai para `/cart`. Para abrir o painel, o tema precisa compartilhar o estado `open`, como o cookbook do drawer descreve.

Assinatura pública: [Cart Contract](https://docs-loja.usecorvex.com.br/reference/contracts/cart.md).

***

## Comportamento no Editor

* Field `menu`: picker de handles ou lista de menus do rascunho da loja.
* Field `color_scheme`: lista esquemas de `config/settings.schema.json`.
* Header aparece em todas as páginas via layout group (não no picker “Adicionar seção” do corpo).

***

## Cuidados

* **Não** assumir `settings.menu` como array de links — sempre resolver via SDK.
* **Não** duplicar o header em `templates/*.json` se já está no layout group.
* Menu vazio: mostrar fallback; loja pode não ter menu publicado ainda.
* Mobile: estado `useState` local à instância do header (vários headers = vários toggles independentes).

***

## Checklist

* [ ] `menu` field com default `main`
* [ ] `useStorefrontMenus([handle])` + `StorefrontNav`
* [ ] `layoutGroups.header` em `theme.json`
* [ ] `groups/header.json` com instância padrão
* [ ] Somente field types [Stable](https://docs-loja.usecorvex.com.br/schema/overview.md)
* [ ] `corvex validate` passa

Implementação completa: `seu tema (adaptado do cookbook)`.


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