visibleWhen

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:

Valor salvo em props.settings / theme settings
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)

Introdução

Temas

Seções

Guias

Exemplos

Storefront Components

Schema

CLI

Dados

SDK

Contratos

Marketplace

visibleWhen

visibleWhen

Quando usar

Sintaxe

Igualdade simples (AND)

OR entre cláusulas

Resolução de valores

Aplica em qualquer item de `settings[]`

Exemplo completo — product-list

Validação (`corvex validate`)

Runtime da section

Limitações atuais

Veja também

​visibleWhen

​Quando usar

​Sintaxe

​Igualdade simples (AND)

​OR entre cláusulas

​Resolução de valores

​Aplica em qualquer item de settings[]

​Exemplo completo — product-list

​Validação (corvex validate)

​Runtime da section

​Limitações atuais

​Veja também

visibleWhen

Quando usar

Sintaxe

Igualdade simples (AND)

OR entre cláusulas

Resolução de valores

Aplica em qualquer item de `settings[]`

Exemplo completo — product-list

Validação (`corvex validate`)

Runtime da section

Limitações atuais

Veja também