Conditions

DYONA Form can declaratively change form behavior according to another field's value.

Try it live

Want to see these declarative conditions react in real time?

Open Conditions in the Lab →

{
  visibleWhen: {
    field: 'customerType',
    operator: 'equals',
    value: 'company'
  }
}

The consuming application does not need if, useState, or conditional JSX to show or hide the field. DYONA Form evaluates the condition from the current form values.

DyonaFieldCondition

type DyonaFieldCondition = {
  field: string;
  operator: DyonaConditionOperator;
  value: DyonaConditionValue;
};

• field is the name of the observed field.
• operator is the comparison DYONA Form performs.
• value is the expected value or collection of values, depending on the operator.

visibleWhen

visibleWhen controls whether a field is shown.

{
  name: 'companyName',
  label: 'Company name',
  type: 'text',
  visibleWhen: {
    field: 'customerType',
    operator: 'equals',
    value: 'company'
  }
}

When the condition is true, the field is shown; when it is false, the field is hidden. visible: false has absolute priority and keeps the field hidden even if visibleWhen is true.

requiredWhen

requiredWhen makes a field required only when its condition is met.

{
  name: 'taxId',
  label: 'Tax ID',
  type: 'text',
  visibleWhen: {field: 'customerType', operator: 'equals', value: 'company'},
  requiredWhen: {field: 'customerType', operator: 'equals', value: 'company'}
}

visibleWhen and requiredWhen can use the same condition. A field can also be required through required: true or a required validation; see Validation for those mechanisms.

Available operators

Operator	Meaning	Expected value
equals	Current value equals the expected value.	Scalar
notEquals	Current value differs from the expected value.	Scalar
greaterThan	Numeric comparison greater than.	Number
lessThan	Numeric comparison less than.	Number
in	Current value belongs to a collection.	Non-empty array
notIn	Current value does not belong to a collection.	Non-empty array

Detailed example: equals

When customerType equals "company", Company name and Tax ID are shown and become required.

{
  name: 'customerType', label: 'Customer type', type: 'select', required: true,
  options: [{value: 'person', label: 'Individual'}, {value: 'company', label: 'Company'}]
},
{
  name: 'companyName', label: 'Company name', type: 'text',
  visibleWhen: {field: 'customerType', operator: 'equals', value: 'company'},
  requiredWhen: {field: 'customerType', operator: 'equals', value: 'company'}
},
{
  name: 'taxId', label: 'Tax ID', type: 'text',
  visibleWhen: {field: 'customerType', operator: 'equals', value: 'company'},
  requiredWhen: {field: 'customerType', operator: 'equals', value: 'company'}
}

Detailed example: greaterThan

When Order amount exceeds 10,000, Approval reason appears and becomes required.

{
  name: 'approvalReason',
  label: 'Approval reason',
  type: 'text',
  visibleWhen: {field: 'orderAmount', operator: 'greaterThan', value: 10000},
  requiredWhen: {field: 'orderAmount', operator: 'greaterThan', value: 10000}
}

Detailed example: in

For Refund or Credit, Request reason appears and becomes required.

{
  name: 'requestReason',
  label: 'Request reason',
  type: 'text',
  visibleWhen: {field: 'requestType', operator: 'in', value: ['refund', 'credit']},
  requiredWhen: {field: 'requestType', operator: 'in', value: ['refund', 'credit']}
}

Detailed example: notEquals

When Employment type is different from Employee, Contract company is shown and becomes required.

{
  name: 'contractCompany',
  label: 'Contract company',
  type: 'text',
  visibleWhen: {field: 'employmentType', operator: 'notEquals', value: 'employee'},
  requiredWhen: {field: 'employmentType', operator: 'notEquals', value: 'employee'}
}

Detailed example: lessThan

When Age is less than 18, Guardian name is shown and becomes required.

{
  name: 'guardianName',
  label: 'Guardian name',
  type: 'text',
  visibleWhen: {field: 'age', operator: 'lessThan', value: 18},
  requiredWhen: {field: 'age', operator: 'lessThan', value: 18}
}

Detailed example: notIn

When Delivery type is neither Pickup nor Digital, Delivery address is shown and becomes required.

{
  name: 'deliveryAddress',
  label: 'Delivery address',
  type: 'text',
  visibleWhen: {field: 'deliveryType', operator: 'notIn', value: ['pickup', 'digital']},
  requiredWhen: {field: 'deliveryType', operator: 'notIn', value: ['pickup', 'digital']}
}

Basic structural rules

• field must reference an existing field.
• A field cannot condition itself.
• operator must be supported.
• in and notIn require a non-empty array.
• greaterThan and lessThan require a numeric value.

Type note

Boolean comparisons are strict. For numbers, DYONA Form allows the currently edited value to arrive temporarily as a numeric string and compares it numerically.

Next steps

• Schema
• Validation
• All currently supported condition operators are covered above.