Conditionals

Fields and containers can be shown, hidden, or have their values changed based on form state using conditional expressions.

Simple condition (leaf)

{
  "nome": "outro_pais",
  "tipo": "texto",
  "condicional": {
    "campo": "pais",
    "operador": "igual",
    "valor": "Other"
  }
}

The outro_pais field only appears when pais === "Other".

Available operators

Operator	Meaning
`igual`	`==`
`diferente`	`!=`
`vazio`	empty or falsy value
`naoVazio`	non-empty value
`contem`	array includes / string includes
`naoContem`	array does not include
`maiorQue`	`>`
`menorQue`	`<`
`maiorOuIgual`	`>=`
`menorOuIgual`	`<=`

AND group

All conditions must be true:

{
  "condicional": {
    "and": [
      { "campo": "tipo_cliente", "operador": "igual", "valor": "PJ" },
      { "campo": "faturamento_anual", "operador": "maiorQue", "valor": 1000000 }
    ]
  }
}

OR group

At least one condition must be true:

{
  "condicional": {
    "or": [
      { "campo": "canal", "operador": "igual", "valor": "email" },
      { "campo": "canal", "operador": "igual", "valor": "sms" }
    ]
  }
}

Nested groups

Groups can be nested for complex logic:

{
  "condicional": {
    "and": [
      {
        "or": [
          { "campo": "plano", "operador": "igual", "valor": "pro" },
          { "campo": "plano", "operador": "igual", "valor": "enterprise" }
        ]
      },
      { "campo": "aceite_termos", "operador": "igual", "valor": true }
    ]
  }
}

Reading from externalData

Use the evento. prefix in campo to compare against values from externalData:

{
  "condicional": {
    "campo": "evento.modoEdicao",
    "operador": "igual",
    "valor": true
  }
}

In the renderer:

<FormRenderer
  schema={schema}
  externalData={{ "evento.modoEdicao": true }}
  onComplete={handler}
/>

Container-level conditionals

Apply a conditional to a whole FormContainer to show/hide an entire section. All fields inside it are also hidden and excluded from validation:

{
  "titulo": "Commercial Address",
  "id": "secao_comercial",
  "ordem": 2,
  "condicional": {
    "campo": "tipo_cliente",
    "operador": "igual",
    "valor": "PJ"
  },
  "campos": [
    {
      "nome": "cnpj",
      "tipo": "cnpj",
      "titulo": "CNPJ",
      "ordem": 1,
      "obrigatorio": true
    },
    {
      "nome": "razao_social",
      "tipo": "texto",
      "titulo": "Company Name",
      "ordem": 2,
      "obrigatorio": true
    }
  ]
}

When the container is hidden, all its fields are excluded from validation and submission.

setValues — autofill other fields

Use setValues to automatically populate fields when a condition becomes true:

{
  "nome": "mesmo_endereco",
  "tipo": "switch",
  "titulo": "Billing same as shipping",
  "setValues": [
    {
      "condicional": {
        "campo": "mesmo_endereco",
        "operador": "igual",
        "valor": true
      },
      "values": {
        "cep_cobranca": { "campo": "cep_entrega" },
        "cidade_cobranca": { "campo": "cidade_entrega" }
      }
    }
  ]
}

values supports two modes:

Copy from field: { "campo": "otherField" } — copies the current value of otherField
Literal value: { "valor": "fixed" } — sets a fixed literal value

clearedValue — reset value when hidden

Define the value applied to a field when it becomes hidden by a conditional:

{
  "nome": "desconto_parceiro",
  "tipo": "number",
  "condicional": { "campo": "eh_parceiro", "operador": "igual", "valor": true },
  "clearedValue": 0
}

Without clearedValue, the field's previous value stays in place even after it's hidden. Set it to null to explicitly clear the value:

{
  "nome": "numero_filhos",
  "clearedValue": null
}

Evaluate conditionals programmatically

import { evaluateFieldCondition } from "@schema-forms-data/renderer";

const visible = evaluateFieldCondition(
  field.condicional,
  formValues,
  externalData,
);

Full multi-step example

{
  "titulo": "Registration",
  "passos": [
    {
      "titulo": "Personal Data",
      "ordem": 1,
      "campos": [
        {
          "nome": "nome_completo",
          "tipo": "texto",
          "titulo": "Full Name",
          "ordem": 1,
          "obrigatorio": true
        },
        {
          "nome": "tipo_pessoa",
          "tipo": "select",
          "titulo": "Type",
          "ordem": 2,
          "opcoes": [
            { "label": "Individual", "value": "PF" },
            { "label": "Company", "value": "PJ" }
          ]
        },
        {
          "nome": "cpf",
          "tipo": "cpf",
          "titulo": "CPF",
          "ordem": 3,
          "obrigatorio": true,
          "condicional": {
            "campo": "tipo_pessoa",
            "operador": "igual",
            "valor": "PF"
          },
          "clearedValue": null
        },
        {
          "nome": "cnpj",
          "tipo": "cnpj",
          "titulo": "CNPJ",
          "ordem": 4,
          "obrigatorio": true,
          "condicional": {
            "campo": "tipo_pessoa",
            "operador": "igual",
            "valor": "PJ"
          },
          "clearedValue": null
        }
      ]
    }
  ]
}

Condição simples (folha)

{
  "nome": "outro_pais",
  "tipo": "texto",
  "condicional": {
    "campo": "pais",
    "operador": "igual",
    "valor": "Outro"
  }
}

O campo outro_pais só aparece quando pais === "Outro".

Operadores disponíveis

Operador	Significado
`igual`	`==`
`diferente`	`!=`
`vazio`	valor vazio ou falsy
`naoVazio`	valor preenchido
`contem`	array inclui / string inclui
`naoContem`	array não inclui
`maiorQue`	`>`
`menorQue`	`<`
`maiorOuIgual`	`>=`
`menorOuIgual`	`<=`

Grupo AND

Todas as condições precisam ser verdadeiras:

{
  "condicional": {
    "and": [
      { "campo": "tipo_cliente", "operador": "igual", "valor": "PJ" },
      { "campo": "faturamento_anual", "operador": "maiorQue", "valor": 1000000 }
    ]
  }
}

Grupo OR

Pelo menos uma condição precisa ser verdadeira:

{
  "condicional": {
    "or": [
      { "campo": "canal", "operador": "igual", "valor": "email" },
      { "campo": "canal", "operador": "igual", "valor": "sms" }
    ]
  }
}

Grupos aninhados

Grupos podem ser aninhados para lógicas complexas:

{
  "condicional": {
    "and": [
      {
        "or": [
          { "campo": "plano", "operador": "igual", "valor": "pro" },
          { "campo": "plano", "operador": "igual", "valor": "enterprise" }
        ]
      },
      { "campo": "aceite_termos", "operador": "igual", "valor": true }
    ]
  }
}

Ler de externalData

Use o prefixo evento. no campo para comparar com valores de externalData:

{
  "condicional": {
    "campo": "evento.modoEdicao",
    "operador": "igual",
    "valor": true
  }
}

No renderer:

<FormRenderer
  schema={schema}
  externalData={{ "evento.modoEdicao": true }}
  onComplete={handler}
/>

Condicional em containers

Containers inteiros podem ser ocultados. Todos os campos dentro deles também são ocultados e ignorados na validação:

{
  "id": "container-endereco",
  "ordem": 2,
  "condicional": {
    "campo": "tipo_entrega",
    "operador": "igual",
    "valor": "fisico"
  },
  "campos": [...]
}

Definir valores ao tornar-se visível (`setValues`)

Quando uma condicional passa de falso para verdadeiro, você pode injetar valores em outros campos:

{
  "nome": "plano",
  "tipo": "select",
  "opcoes": [
    { "valor": "gratis", "label": "Grátis" },
    { "valor": "pago", "label": "Pago" }
  ],
  "condicional": {
    "campo": "tipo_usuario",
    "operador": "igual",
    "valor": "admin"
  },
  "setValues": [{ "campo": "plano", "valor": "pago" }]
}

Limpar valor ao ocultar (`clearedValue`)

Por padrão, campos ocultos por condicionais mantêm seu valor no estado interno. Para limpá-lo, use clearedValue:

{
  "nome": "codigo_pais",
  "tipo": "texto",
  "condicional": {
    "campo": "internacional",
    "operador": "igual",
    "valor": true
  },
  "clearedValue": null
}

Quando o campo é ocultado, o valor é definido como null.

Avaliar condicionais programaticamente

import { evaluateFieldCondition } from "@schema-forms-data/renderer";

const visivel = evaluateFieldCondition(
  field.condicional,
  formValues,
  externalData,
);

} }

The renderer will read `externalData.modoEdicao` for comparison.

## Container-level conditionals

Apply a conditional to a whole `FormContainer` to show/hide an entire section:

```json
{
  "titulo": "Endereço Comercial",
  "id": "secao_comercial",
  "ordem": 2,
  "condicional": {
    "campo": "tipo_cliente",
    "operador": "igual",
    "valor": "PJ"
  },
  "campos": [
    {
      "nome": "cnpj",
      "tipo": "cnpj",
      "titulo": "CNPJ",
      "ordem": 1,
      "obrigatorio": true
    },
    {
      "nome": "razao_social",
      "tipo": "texto",
      "titulo": "Razão Social",
      "ordem": 2,
      "obrigatorio": true
    }
  ]
}

When the container is hidden, all its fields are excluded from validation and submission.

setValues — autofill other fields

Use setValues to automatically populate fields when a condition becomes true:

{
  "nome": "mesmo_endereco",
  "tipo": "switch",
  "titulo": "Billing same as shipping",
  "setValues": [
    {
      "condicional": {
        "campo": "mesmo_endereco",
        "operador": "igual",
        "valor": true
      },
      "values": {
        "cep_cobranca": { "campo": "cep_entrega" },
        "cidade_cobranca": { "campo": "cidade_entrega" }
      }
    }
  ]
}

values supports two modes:

Copy from field: { "campo": "outroCampo" } — copies the current value of outroCampo
Literal value: { "valor": "fixo" } — sets a fixed literal value

clearedValue — reset value when hidden

Define the value applied to a field when it becomes hidden by a conditional:

{
  "nome": "desconto_parceiro",
  "tipo": "number",
  "condicional": { "campo": "eh_parceiro", "operador": "igual", "valor": true },
  "clearedValue": 0
}

Without clearedValue, the field's previous value stays in place even after it's hidden. Set it to null to explicitly clear the value:

{
  "nome": "numero_filhos",
  "clearedValue": null
}

Full multi-step example

{
  "titulo": "Cadastro",
  "passos": [
    {
      "titulo": "Dados Pessoais",
      "ordem": 1,
      "campos": [
        {
          "nome": "nome_completo",
          "tipo": "texto",
          "titulo": "Nome",
          "ordem": 1,
          "obrigatorio": true
        },
        {
          "nome": "tipo_pessoa",
          "tipo": "select",
          "titulo": "Tipo",
          "ordem": 2,
          "opcoes": [
            { "label": "Pessoa Física", "value": "PF" },
            { "label": "Pessoa Jurídica", "value": "PJ" }
          ]
        },
        {
          "nome": "cpf",
          "tipo": "cpf",
          "titulo": "CPF",
          "ordem": 3,
          "obrigatorio": true,
          "condicional": {
            "campo": "tipo_pessoa",
            "operador": "igual",
            "valor": "PF"
          },
          "clearedValue": null
        },
        {
          "nome": "cnpj",
          "tipo": "cnpj",
          "titulo": "CNPJ",
          "ordem": 4,
          "obrigatorio": true,
          "condicional": {
            "campo": "tipo_pessoa",
            "operador": "igual",
            "valor": "PJ"
          },
          "clearedValue": null
        }
      ]
    }
  ]
}

Simple condition (leaf)​

Available operators​

AND group​

OR group​

Nested groups​

Reading from externalData​

Container-level conditionals​

setValues — autofill other fields​

clearedValue — reset value when hidden​

Evaluate conditionals programmatically​

Full multi-step example​

Condição simples (folha)​

Operadores disponíveis​

Grupo AND​

Grupo OR​

Grupos aninhados​

Ler de externalData​

Condicional em containers​

Definir valores ao tornar-se visível (setValues)​

Limpar valor ao ocultar (clearedValue)​

Avaliar condicionais programaticamente​

setValues — autofill other fields​

clearedValue — reset value when hidden​

Full multi-step example​

Simple condition (leaf)

Available operators

AND group

OR group

Nested groups

Reading from externalData

Container-level conditionals

setValues — autofill other fields

clearedValue — reset value when hidden

Evaluate conditionals programmatically

Full multi-step example

Condição simples (folha)

Operadores disponíveis

Grupo AND

Grupo OR

Grupos aninhados

Ler de externalData

Condicional em containers

Definir valores ao tornar-se visível (`setValues`)

Limpar valor ao ocultar (`clearedValue`)

Avaliar condicionais programaticamente

setValues — autofill other fields

clearedValue — reset value when hidden

Full multi-step example