Display Formula

Use JSONata display formulas to show or hide fields and screen elements from current row, form, user, or context data.

A Display Formula is a conditional visibility rule. It lets Buzzy decide whether a field or screen element should be visible at runtime by evaluating a JSONata expression against the current data context.

Use Display Formula for progressive forms, conditional sections, role-specific interface hints, and workflow states. Do not use it as a security boundary. If a user must not access data, configure row access, field access, Private Data, Teams, or People settings instead.

How It Works

Display Formula has two parts:

Setting	What it does
Show	Shows the field or element only when the formula evaluates to true.
Hide	Hides the field or element when the formula evaluates to true.

Buzzy evaluates the formula with JSONata. The formula can reference:

• fields on the current row or form

• _contextRow when the screen or form has a parent/current row context

• _currentUrl in capture forms

• _id for the generated or current row id

• user._id, user.email, and user.highestRole

• system fields such as userID, viewers, isLocked, and submitted

Fields with spaces or special characters must be wrapped in backticks:

`Favourite food type` = "Other"

Strings use quotes, booleans use true and false, and formulas are case-sensitive.

Common Pattern: Show an "Other" Field

Scenario: a form has a Selection field named Favourite food type with an Other option. You only want the free-text field to appear when the user selects Other.

Set the free-text field's Display Formula mode to Show, then use:

`Favourite food type` = "Other"

If the source field is a Checkboxes field, its value is an array. Use the JSONata in operator:

"Other" in `Favourite food type`

Role-Based Visibility

To show an element only to admins/authors:

user.highestRole = "owner" or user.highestRole = "author"

To show an element to owners/authors, or to users who are not in the row's viewers list:

(user.highestRole = "owner" or user.highestRole = "author") or $not(user._id in viewers)

To show an element only to the row creator:

user._id = userID

These examples are useful for interface behavior. They do not replace data permissions.

Workflow-State Examples

Show a field only when a row is not locked:

isLocked = false

Or, more compactly:

$not(isLocked)

Show a payment section only when payment is required and the permission/signature steps are complete:

isLocked = false
and $boolean(`Permission`)
and $boolean(`Signature`)
and (`Permission` = "Yes" ?
  $boolean(`Emergency contact`)
  and (`Payment required` = "Yes" ?
    $boolean(`Payment options`)
  : true)
: true)

Field Formula vs Screen Element Formula

Display Formula is used in two related places:

Where	Context	Typical use
Datatable field settings	Current form or row data	Show or hide individual fields in a form, detail view, or result row.
Screen element visibility	Current screen, row, form, user, and context data	Show or hide containers, sections, form areas, empty-state branches, and other UI elements.

In the screen editor, the preview simulation panel can force Display Formula branches on or off so you can inspect both paths without changing live data.

Debugging Display Formula

If a formula does not behave as expected:

1. Confirm the field labels and internal names match the formula exactly.

2. Use backticks around labels with spaces or punctuation.

3. Check whether the source value is a string, number, boolean, array, or object.

4. Test both Show and Hide logic carefully. A Show rule hides the element when the formula is false; a Hide rule hides it when the formula is true.

5. Use the In-App Debugging to inspect screen context, bindings, fields, actions, and runtime errors.

For more JSONata syntax examples, see Formula language and jsonata.org.