Dynamic properties, choices, bindings and events
This guide explains, from the control developer's side, how values reach your control and how your control changes form data and triggers automations. It pairs with the author's view in Use installed custom controls in the interface designer: what an author configures there is what your control receives here.
The examples come from two samples in Studio's developer kit (Authorization → Plugins → Developer kit): the UI-only starter and the Google Maps sample (the Service visits map). For the lifecycle and host services, see the developer guide.
Value types and what the control receives
The host resolves every property before your control sees it. A control never receives expression text, a binding path or a raw server message: only a typed value and a state.
| Kind | Delivered as | Example (from the test kit's SAMPLE_VALUES) |
|---|---|---|
TEXT |
string | "Riyadh" |
INTEGER |
number (whole) | 42 |
LONG |
string of digits, exact | "9007199254740993" |
DECIMAL |
string, exact | "1234.50" |
BOOLEAN |
boolean | true |
DATE, TIME, LOCAL_DATETIME, INSTANT |
ISO text | "2026-11-09", "09:30:00", "2026-11-09T09:30:00", "2026-11-09T06:30:00Z" |
UUID |
string | "0b8f1c2e-4d5a-4f6b-9c7d-8e9f0a1b2c3d" |
JSON |
JSON value | { "visits": 3, "tags": ["a", "b"] } |
ENUM |
the member string, never its label | "OPEN" |
DOCUMENT, USER, GROUP, FOLDER, CABINET, LIFECYCLE_REF, FUNCTION_REF, RECORD_REF |
a reference object with kind |
{ "kind": "user", "userId": "user-1" } |
RECORD |
a plain object | { "name": "Visit 1", "lat": "24.7136", "lng": "46.6753" } |
With "cardinality": "MANY", the value is a list of these. The map sample's locations is a list of RECORD objects.
Keep exact numbers exact. Never convert a LONG or DECIMAL to a JavaScript number for display or comparison: show
the text as delivered. The mixed sample shows a server-computed distance this way (343.557 km). Write LONG and
DECIMAL defaults as strings too.
Generated types follow the declaration: PropertiesOf<typeof declaration> gives region the type
'north' | 'south' | 'east' | 'west' | null in the starter, so a typo is a compile error.
Source modes
An author sets each property in one of the modes you allow in sourceModes:
| Manifest | Designer | The control receives |
|---|---|---|
LITERAL |
Value | the typed literal the author entered (your default is saved as one when the control is placed) |
| not set | Use default, or never set | nothing: the key is absent; apply your declared default yourself |
EXPRESSION |
Expression | the expression's result, re-evaluated when what it reads changes |
BINDING |
Data | the current value at a data path, such as a Local (locals:region) or a published list (data.visits) |
Allow fewer modes only for a reason, and say it in restrictionReason. Typical reasons from the samples:
- presentation text that must never come from form data: Value and Expression only;
- an author's layout or configuration choice: Value only;
- records, which cannot be typed in: Expression and Data only ("Visits are records: they come from form data or an expression (for example a query rule), never typed in as a value.");
- a public browser key: Value only, with a warning that everyone who opens the form can read it.
Expressions in control properties are checked at publication. They must not change data, depend on time or
randomness, read undeclared inputs, or read computed values of the interface. When a running form's expression result
does not fit your property, the host withholds it and sends the property as error with "This value could not be
worked out."; a Value or Data setting that does not fit arrives as invalid with "This value does not fit this
property." Your control shows the reason; it never falls back to a default or a first choice.
Property states
context.propertyStates and update({ propertyStates }) give each property one state:
| State | Show |
|---|---|
ready |
the value |
loading |
a loading message; disable choosing |
empty |
nothing selected |
invalid (reason) |
the reason; for "This choice is no longer offered." also the retained value, marked invalid, with corrective choices |
error (reason) |
the reason |
unavailable |
nothing selected |
Values and states arrive together. An update whose properties contains a key set to undefined withdraws that value:
clear it, and show the state. The SDK reference's complete example (control.ts in
A complete control) shows the pattern.
Two states must stay choosable, because the host accepts the write (see
Property states in the developer guide): unavailable for an unset binding, and
invalid with the reason "This choice is no longer offered." The starter shows that reason above its still-operable
choices.
Choices
A choice property is usually an ENUM. Its declared members (enumValues, labelled by memberLabels) are the choices
when the author configures nothing else. With dynamicOptions, you let the author supply a list:
dynamicOptions |
The author configures | You receive |
|---|---|---|
EXPRESSION |
an expression returning a list of values (at most 1,000, unique; for an ENUM, declared members only) | each item { value, label }, where label is the value written as text ("north"), not the member label |
DATA_SOURCE, stored data |
rows in form data, with a value field, a label field and an optional disabled-reason field | { value, label, disabledReason? } from the rows |
DATA_SOURCE, records |
a published record type, with value and label fields, searched on the server | pages of { value, label }, with hasMore |
The list arrives in context.options[key] and update({ options }) as { status, items, hasMore }, separately from the
property's value. Its status is one of:
status |
Meaning | Starter shows |
|---|---|---|
ready |
items is the current resolved list, or the current page of a server search |
the items |
loading |
being worked out, or a value it depends on is loading | "Loading regions…" |
empty |
no choices; dependent lists are empty until what they depend on is set | "No regions are offered." |
error |
could not be worked out or read, or broke a rule; never a partial list | "The regions could not be loaded." |
unavailable |
no dynamic list here | the declared members |
Rules for your control:
- Store
value, neverlabel.setOutputtakes the value. - Only
unavailablefalls back to the declared members. An empty, loading or failed list offers nothing; do not show the declared members instead. (The starter'schoicesOfinsrc/ExampleControl.tsximplements exactly this.) - Show
disabledReasonand refuse to choose a disabled item. The starter setsaria-disabledand atitle. - Labels. For expression choices the host's label is the value as text. If you want your member labels there, look
the value up in your declaration's
memberLabels, as the starter does for the declared members. - A page is not the whole list. A
readylist withhasMore: trueis one page of a server search. OnlyhasMore: falsemeansitemsis complete. Never decide from one page that the current value is not offered; the host does that and tells you through the "This choice is no longer offered." state. - Replace, never merge. Each update is the whole current list. The host delivers only the latest answer of a
search, never a stale one;
runConformancechecks that your control does not keep stale items.
Searching on the server
Record choices are read a page at a time: at most 50 items, with hasMore: true when more exist. When hasMore is true,
offer a search box and call host.searchOptions(key, text) as the person types (at most 160 characters; empty text asks
for the first page). The host debounces it (250 ms), authorizes and bounds the read, and delivers the answer as a new
options update. A read that takes more than 10 seconds becomes error. searchOptions returns not-declared for a
property whose choices are not searched on the server. Do not try to load every record.
Once a search text is active, keep the search box and a way to clear it (which calls searchOptions(key, '')) visible,
even when the narrowed result has hasMore: false, is empty or is error: the host keeps the last search text until
you call again, so hiding the box would leave the person stuck with a filtered list.
Dependent lists
An author can make record choices depend on up to three other values, for example cities filtered by the chosen
country. Your control needs no code for this: while a value it depends on is unset, the list is empty; when it
changes, a loading list and then the new list arrive, and late answers for the previous value are dropped. A list that
would depend on its own value is refused at publication.
Bindings and outputs
An output lets a person change form data through your control. The host writes the value only when all of these hold:
- the output is declared, with
propertynaming the property it writes; - the property is not declared
readOnly; - the author bound that property with Data to a declared, non-computed Local or Input;
- the placed control is not disabled or read-only in the form;
- the Local or Input has the same type, and the type is one of TEXT, UUID, ENUM, INTEGER, BOOLEAN, DATE or TIME;
- the instance is ready in a running form (a published form, or the designer's Preview, whose values are never saved), and the bound value is not loading;
- the value fits the declared type;
- the value differs from the current one.
Otherwise nothing changes, and setOutput returns not-declared (no such output, or its property is not declared), suppressed (read-only, not bound, disabled or read-only node, design canvas, or a binding in an error or non-recoverable invalid state), not-ready (not running yet, or the binding is loading), invalid-value or unchanged. A binding that is unset (unavailable, empty) or holds a choice that is "no longer offered" can be written. LONG, DECIMAL, RECORD
and reference values are never written back: carry an identifier instead. The map sample's selection is the TEXT
selectedJobId, not the visit record.
The host does not check that an output comes from a person's interaction. That is your control's obligation (see Only genuine input may change data).
What happens to an accepted value:
- It goes into the form's normal draft, with dirty state, validation, reset, save and cancel. Your control never saves.
- The bound property then changes, and your control receives the new value through
update. Do not echo it back:setOutputof the current value returnsunchanged, and the form does not become dirty. - A Reset form step returns the value; that is not a person's choice, so change automations do not run.
Tell authors to bind. In the property's description, say that it must be bound to form data to be editable, as
the starter does: "The chosen region. Bind it to form data to let people change it." A property set by Value shows its
value but refuses every edit. The tutorial's step 7 shows the
binding.
Inside a repeater, a control runs once per row. A Data path such as city reads that row's field, but an output to a
row field is refused (a row field has no declared type). Use an event for actions on a row.
Events
An event reports a person's interaction to the automations the author connects:
// The starter's confirm, called from Enter and double-click handlers (src/ExampleControl.tsx)
host.emit('regionConfirmed', { region: choice.value });
- Declare it with a
label(what authors see, for example Region confirmed) and a typedpayload. Authors read fields asevent.<name>, for example=event.region. - Choose a key that is not reserved (see Events): a reserved key is never offered to
authors and
emitreturnsnot-declared. - Emit only from the handler of a person's pointer or key input inside your control, within 5 seconds. Never from
mount,update, a refresh, or because a property changed. The map sample'smarkerSelecteddescription says so to authors: "Never sent because properties changed." - The payload must match the declared fields and types, and be at most 16 KiB. Otherwise nothing runs.
- Events are not sent on the design canvas, while the control is disabled or read-only, or when no interaction licenses them. In the designer's Preview, connected steps run under the preview's rules.
- Each automation step runs with the current person's rights, with the platform's own confirmation, duplicate protection and audit.
Choose events for "something happened" (a visit was chosen, a region was confirmed) and outputs for "this is the new value". The starter has both for the same interaction: a click is an output, Enter is an output and an event.
Checklist
- [ ] Every property declares
sourceModes, and arestrictionReasonwhen it allows fewer than three. - [ ] Defaults are canonical: LONG and DECIMAL as strings, INTEGER as a number.
- [ ] The control renders every property state and every option status, and keeps choosing possible for an unset binding and a "no longer offered" value.
- [ ] Only
unavailablefalls back to the declared members; values are stored, never labels. - [ ] Outputs and events are called only from a person's interaction, and every
HostResultis checked. - [ ] Writable properties tell authors to bind them with Data.
- [ ] Tests cover the above with
mountForTest, andrunConformancepasses.