Form conditions

Show and enable fields from typed form values.

Create conditions through the form whose action defines the input type. form.when(path) selects a typed path from current form values. The path can include group keys and array indexes. form.ref(path) reads another value on the right side of a comparison.

import { defineResource, fields, form } from '@backlit/sdk'
import { z } from 'zod'
const orders = defineResource('orders', [])
const save = orders.action(
  'save',
  z.object({
    gift: z.boolean(),
    note: z.string().optional(),
    approved: z.boolean(),
  }),
  () => {}
)
orders.view('create', () => {
  const editor = form(save)
  return editor
    .setContent([
      editor.fields(
        fields.boolean('gift'),
        fields
          .text('note')
          .revealWhen(editor.when('gift').equals(true)),
        fields
          .boolean('approved')
          .enableWhen(editor.when('note').isFilled())
      ),
    ])
    .withInitialData({
      gift: true,
      note: 'Happy birthday',
      approved: false,
    })
})
export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "create",
    "slots": {
      "content": [
        {
          "kind": "form",
          "target": {
            "resource": "orders",
            "action": "save"
          },
          "initial": {
            "gift": true,
            "note": "Happy birthday",
            "approved": false
          },
          "slots": {
            "content": [
              {
                "kind": "form-fields",
                "fields": [
                  {
                    "kind": "boolean",
                    "name": "gift",
                    "label": ""
                  },
                  {
                    "kind": "text",
                    "name": "note",
                    "label": "",
                    "reveal": {
                      "kind": "condition-predicate",
                      "path": "gift",
                      "op": "eq",
                      "right": {
                        "value": true
                      }
                    }
                  },
                  {
                    "kind": "boolean",
                    "name": "approved",
                    "label": "",
                    "enable": {
                      "kind": "condition-predicate",
                      "path": "note",
                      "op": "filled"
                    }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  }
}

A field has revealWhen(condition) and enableWhen(condition). These methods return configured copies. Keep or place the returned field. Panels, sections, form field blocks, and repeaters support revealWhen. Only fields support enableWhen.

Conditions run in the client. They do not replace action validation or server authorization. Hidden fields are removed from the form. Disabled fields do not submit values. Make the action schema accept these omissions when required.

Operators

The selected path type determines the available operators.

Value	Operators
Any value	`isMissing`, `isPresent`, `isNull`, `isNotNull`, `isEmpty`, `isNotEmpty`, `isFilled`, `isUnfilled`
String, number, boolean	`equals`, `doesNotEqual`, `isOneOf`, `isNoneOf`
String or number	`isGreaterThan`, `isAtLeast`, `isLessThan`, `isAtMost`, `isBetween`
String	`containsText`, `startsWith`, `endsWith`
String or array	`lengthEquals`, `lengthIsGreaterThan`, `lengthIsAtLeast`, `lengthIsLessThan`, `lengthIsAtMost`
Array of scalars	`contains`, `containsAny`, `containsAll`
Array of objects	`some`, `every`, `none` with a row condition callback

isBetween(lower, upper) includes both bounds. Combine conditions with form.all(first, ...rest), form.any(first, ...rest), or form.none(first, ...rest). Each group requires at least one condition. For an array of objects, the callback receives paths relative to each row. Repeaters also provide a row condition composer. See Repeaters.

A missing value is undefined; a null value is null. Empty text and empty arrays are empty. isFilled requires a value that is present, non-null, and not empty. The values 0 and false are filled.