> For the complete documentation index, see [llms.txt](https://docs.buzzy.buzz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buzzy.buzz/the-building-blocks/datatables-fields-and-data/display-formula.md).

# Display Formula

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:

```jsonata
`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:

```jsonata
`Favourite food type` = "Other"
```

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

```jsonata
"Other" in `Favourite food type`
```

## Role-Based Visibility

To show an element only to admins/authors:

```jsonata
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:

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

To show an element only to the row creator:

```jsonata
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:

```jsonata
isLocked = false
```

Or, more compactly:

```jsonata
$not(isLocked)
```

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

```jsonata
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](/troubleshooting/in-app-debugging.md) to inspect screen context, bindings, fields, actions, and runtime errors.

For more JSONata syntax examples, see [Formula language](/the-building-blocks/datatables-fields-and-data/formulas.md) and [jsonata.org](https://jsonata.org/).