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

# visibleWhen

> Exibir settings no Inspector apenas quando outras configurações têm valores específicos.

Propriedade **OPTIONAL** em qualquer item de `settings[]` (section, block ou theme settings) que controla **visibilidade no Inspector**.

O valor salvo **não é apagado** quando o campo some — apenas fica oculto na UI. O runtime da section continua recebendo o valor em `settings`.

***

## Quando usar

| Cenário | Exemplo |
| - | - |
| Layout alternativo | Colunas da grade só quando `layout === "grid"` |
| Cor personalizada | Campos `color` só quando `colorMode === "custom"` |
| Feature flag | Parcelas só quando `showInstallments === true` |
| Texto de ajuda contextual | `paragraph` visível só no modo relevante |

***

## Sintaxe

### Igualdade simples (AND)

Objeto com pares `settingId → valor`. **Todas** as chaves devem coincidir:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "gridColumnsMobile",
  "type": "range",
  "label": "Colunas no celular (grade)",
  "min": 1,
  "max": 3,
  "default": 2,
  "visibleWhen": { "layout": "grid" }
}
```

Múltiplas condições no mesmo objeto = **AND**:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
"visibleWhen": {
  "layout": "grid",
  "showAddToCart": true
}
```

### OR entre cláusulas

Array de objetos — **qualquer** cláusula verdadeira torna o campo visível:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
"visibleWhen": [
  { "layout": "carousel" },
  { "layout": "grid", "featured": true }
]
```

***

## Resolução de valores

O Editor compara com o valor **atual** do setting:

1. Valor salvo em `props.settings` / theme settings
2. Se ausente, usa `default` do schema

Comparação: **igualdade estrita** (`===`). Tipos suportados no contrato: `string`, `number`, `boolean`.

***

## Aplica em qualquer item de `settings[]`

`visibleWhen` funciona em campos com `id` **e** em itens de layout:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "paragraph",
  "content": "No carrossel, define quantos produtos aparecem por vez.",
  "visibleWhen": { "layout": "carousel" }
}
```

Headers (`type: "header"`) só aparecem quando há **pelo menos um campo visível** logo abaixo no grupo.

***

## Exemplo completo — product-list

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "product-list",
  "name": "Grade de produtos",
  "category": "Produtos",
  "settings": [
    {
      "type": "select",
      "id": "layout",
      "label": "Exibição",
      "default": "carousel",
      "options": [
        { "value": "carousel", "label": "Carrossel" },
        { "value": "grid", "label": "Grade" }
      ]
    },
    {
      "type": "range",
      "id": "carouselPerPageMobile",
      "label": "Colunas no celular (carrossel)",
      "min": 1,
      "max": 3,
      "default": 2,
      "visibleWhen": { "layout": "carousel" }
    },
    {
      "type": "range",
      "id": "gridColumnsMobile",
      "label": "Colunas no celular (grade)",
      "min": 1,
      "max": 3,
      "default": 2,
      "visibleWhen": { "layout": "grid" }
    },
    {
      "type": "checkbox",
      "id": "showInstallments",
      "label": "Mostrar parcelamento",
      "default": true
    },
    {
      "type": "range",
      "id": "installmentCount",
      "label": "Número de parcelas",
      "min": 2,
      "max": 12,
      "default": 12,
      "visibleWhen": { "showInstallments": true }
    },
    {
      "type": "select",
      "id": "addToCartButtonColorMode",
      "label": "Cor do botão",
      "default": "theme",
      "options": [
        { "value": "theme", "label": "Cor principal do tema" },
        { "value": "custom", "label": "Personalizada" }
      ]
    },
    {
      "type": "color",
      "id": "addToCartButtonColor",
      "label": "Fundo do botão",
      "default": "#000000",
      "visibleWhen": { "addToCartButtonColorMode": "custom" }
    }
  ]
}
```

***

## Validação (`corvex validate`)

| Regra | Erro |
| - | - |
| `visibleWhen` deve ser objeto ou array de objetos | shape inválido |
| Cada cláusula precisa de ≥ 1 chave | objeto vazio |
| Valores devem ser `string`, `number` ou `boolean` | tipo inválido |
| Cada chave deve ser `id` de outro setting no mesmo schema | referência inexistente |

`header` e `paragraph` **não** podem ser referenciados em `visibleWhen` — apenas campos com `id` persistido.

***

## Runtime da section

**Não** aplique `visibleWhen` no JSX da section. O componente deve ler todos os settings que precisa; a condicional é só do Inspector.

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Correto — usa o valor independente da visibilidade no editor
const columns =
  settings.layout === 'grid'
    ? settings.gridColumnsMobile
    : settings.carouselPerPageMobile;
```

***

## Limitações atuais

* Sem operadores (`>`, `!=`, `contains`) — apenas igualdade exata
* Sem referência a theme settings globais
* Sem aninhar `visibleWhen` em cadeia automática (cada campo declara sua própria condição)

***

## Veja também

* [Schema Contract](https://docs-loja.usecorvex.com.br/reference/contracts/schema.md)
* [Organização de schemas](https://docs-loja.usecorvex.com.br/guides/schema-organization.md)
* [Schema overview](https://docs-loja.usecorvex.com.br/schema/overview.md)


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