Atlas Forms
Visibility Expression Syntax
Visibility expressions are evaluated in a sandboxed JavaScript-like context. The expression has access to the values object — the current form value map — and a limited set of built-in functions. The expression must return a truthy or falsy value.
Reading Field Values
// All control values are accessible via the 'values' object
// Key = control id, Value = current value
values['country'] // String: current value of the 'country' control
values['age'] // Number: current value of the 'age' control
values['consent'] // Boolean: current value of a checkbox
values['tags'] // Array: current value of a multi-select
values['some-control'] // undefined if control has no value yetCommon Expression Patterns
| Pattern | Expression |
|---|---|
| Equal to a value | values['country'] === 'GB' |
| Not equal to a value | values['type'] !== 'individual' |
| Boolean field is true | values['has-different-billing'] === true |
| Field is not empty | !!values['company-name'] |
| Field is empty | !values['company-name'] |
| One of several values | ['high', 'critical'].includes(values['risk-level']) |
| NOT one of several values | !['low', 'info'].includes(values['risk-level']) |
| Numeric comparison | values['age'] >= 18 |
| AND condition | values['country'] === 'GB' && values['vat-registered'] === true |
| OR condition | values['mode'] === 'express' || values['mode'] === 'priority' |
| Array contains value | values['roles'].includes('admin') |
| String starts with | values['code'].startsWith('UK-') |
Safe Null Handling
// Problem: if 'country' is undefined, === 'GB' returns false (which is correct)
// But: values['tags'].includes('admin') throws if 'tags' is undefined
// Safe array check:
"visibilityRule": "(values['tags'] || []).includes('admin')"
// Safe string check:
"visibilityRule": "(values['code'] || '').startsWith('UK-')"
// Nullish coalescing style:
"visibilityRule": "values['age'] != null && values['age'] >= 18"What Is NOT Available
| Unavailable | Alternative |
|---|---|
Async calls, fetch(), await | Pre-load data as a form control value and read from values |
DOM access (document, window) | N/A — expressions are sandboxed |
eval(), Function() | N/A — blocked by sandbox |
| Multi-line expressions | Keep expressions as single expressions; use helper values to decompose complexity |
| Custom functions | Register a computed field using engine.getComputedValue() and read its result from values |
Expression Error Handling
If a visibility expression throws (e.g., due to a null dereference or a syntax error), the engine treats the error as a failed visibility check — the control is hidden and a warning is logged to the console. Always test expressions in Atlas Forms Studio before deploying.
Keep Expressions Short and Readable
If your expression is longer than about 80 characters, consider whether a computed field would be clearer. A computed field that evaluates to a boolean (
isUkVatRequired) makes the visibility rule trivially readable: values['isUkVatRequired'] === true.