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:

{
  "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:

"visibleWhen": {
  "layout": "grid",
  "showAddToCart": true
}

OR entre cláusulas

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

"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:

{
  "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

{
  "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.

// 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
• Organização de schemas
• Schema overview