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

# Settings globais nas sections

> Como ligar props de section/bloco/snippet às configurações globais do tema.

Use este padrão quando um campo da section deve **seguir o Tema → Global** (ex.: cor de destaque), mas ainda permitir **override local** (“Personalizado”).

Fluxo na Corvex Store:

```
Configuração global
Cor de destaque = #8758F0
        ↓
Barra promocional
Cor de fundo = [Usar global: Cor de destaque]
        ↓
#8758F0 (atualiza sozinho se o global mudar)
```

***

## 1. Defina o token global

Em `config/settings.schema.json`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "groups": [
    {
      "name": "Cores",
      "settings": [
        {
          "id": "color_secondary",
          "type": "color",
          "label": "Cor de destaque",
          "default": "#8758F0"
        }
      ]
    }
  ]
}
```

Esse painel aparece em **Theme → Global** no editor. O valor salvo fica em `settingsData` da loja.

***

## 2. Declare `themeLink` no schema da section

Em `sections/promo-bar/schema.json`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "backgroundColor",
  "type": "color",
  "label": "Cor de fundo",
  "default": "@theme.color_secondary",
  "themeLink": "color_secondary"
}
```

| Campo | Significado |
| - | - |
| `default` | Valor inicial. Use `@theme.{id}` para começar ligado ao global. |
| `themeLink` | Id do setting global. O inspector mostra **Usar global: …** e **Personalizado**. |

Várias opções globais:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
"themeLink": ["color_primary", "color_secondary"]
```

***

## 3. Resolva no componente React

Importe de `@corvex/runtime` (ou `@corvex/theme-host`):

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

export default function PromoBarSection({
  settings = {},
  isEditing,
  onSettingsChange,
}) {
  const text = settings.text ?? 'Frete grátis acima de R$ 199';
  const bg = useThemeSetting(
    settings.backgroundColor ?? '@theme.color_secondary',
    '#8758F0'
  );

  return (
    <SectionChrome
      settings={settings}
      isEditing={isEditing}
      onSettingsChange={onSettingsChange}
    >
      <div className="promo-bar" style={{ background: bg }}>
        <InlineText
          tag="span"
          propKey="text"
          value={text}
          isEditing={isEditing}
          onChange={(v) => onSettingsChange?.({ text: v })}
        />
      </div>
    </SectionChrome>
  );
}
```

### API

| Export | Uso |
| - | - |
| `useThemeSetting(value, fallback)` | Hook em sections/blocks (recomendado) |
| `resolveThemeSettingValue(value, settings, fallback)` | Função pura (SSR, testes, snippets) |
| `makeThemeSettingRef('color_secondary')` | Gera `@theme.color_secondary` |
| `isThemeSettingRef(value)` | Detecta referência global |

***

## 4. Valor gravado no campo

| Valor no prop | Significado |
| - | - |
| `@theme.color_secondary` | Ligado ao global — atualiza quando o lojista muda **Tema → Global** |
| `#FF0000` | Cor fixa local (override) |

O inspector grava isso automaticamente quando o lojista escolhe **Usar global** ou **Personalizado**.

***

## 5. CSS variables (alternativa)

Settings globais também viram CSS vars no canvas/preview:

| Setting id | CSS var |
| - | - |
| `color_primary` | `--brand-primary` |
| `color_secondary` | `--accent-primary` |
| `color_text` | `--text-primary` |
| `color_background` | `--surface-app` |

Em CSS do tema:

```css theme={"theme":{"light":"github-light","dark":"github-dark"}}
.promo-bar {
  background: var(--accent-primary);
}
```

Use **`themeLink` + `useThemeSetting`** quando o lojista precisa escolher entre global e personalizado no inspector. Use **só CSS var** quando a section sempre segue o global.

***

## 6. Blocks e snippets

**Blocks** — mesmo padrão: `themeLink` no schema do block + `useThemeSetting` no JSX.

**Snippets** — não têm inspector. Receba o valor já resolvido da section pai:

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
// section
const bg = useThemeSetting(backgroundColor, '#8758F0');
return <PromoBadge text={text} background={bg} />;

// snippet
export default function PromoBadge({ text, background }) {
  return <span style={{ background }}>{text}</span>;
}
```

Ou use `resolveThemeSettingValue(prop, themeSettings, fallback)` se tiver `settingsData` no contexto.

***

## Checklist do dev de tema

1. Id do global em `settings.schema.json` (ex.: `color_secondary`)
2. Campo da section com `"themeLink": "color_secondary"` e default `@theme.color_secondary`
3. Componente usa `useThemeSetting(prop, fallback)`
4. Defaults em `schema.json` com `@theme.color_secondary` onde aplicável
5. Testar: mudar **Tema → Global** e ver a section atualizar sem reabrir o inspector


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