form

form, tile type

The form tile displays scalar inputs editable from the dashboard. Entries can be bound to fields from read form, or to mutable variables used only for browser-side calculations.

read form with
  StartDate : date
  IsTicked : boolean
  Category : text
  MyHidden : text

show form "My settings" a1b4 with
  StartDate as "My start date"
  IsTicked as "Is ticked"
  Category as "My category"
  MyHidden { formAccess: hidden }

show summary "My settings view" c1d4 with
  StartDate
  IsTicked
  Category
  MyHidden

Values read through read form come from dashboard submissions. Runs from the IDE or RunFlow replay the last submission unless overridden there. The last submission is not a programmatic state.

Submitted form values are scalars and persist across runs. A default expression in read form supplies the value when the submitted field is missing or empty. Without an explicit default, primitive fields use their type default (for example 0 for number).

The form namespace can be used to access raw values, but it is not a table.

read form with
  n : number

k = n + 1

show scalar "My counter" with k

Binding form values

show form can display arbitrary scalar expressions bound to a form field via form:"name". Mutable entries can instead remain unbound, as described below.

read form with
  n : number

k = n + 1

show form "Click 'Start run' to increase this counter" a1d2 with
  k form:"n"

Mutable form entries

show form entries can be bound to dash-mutable variables with the mutable annotation. Edits made in the dashboard update the mutable variable and refresh dash expressions that depend on it.

read form with
  IsActive : boolean

mutable Active = IsActive
dash Status = if Active then "enabled" else "disabled"

show form "Settings" a1b2 with
  Active mutable form:"IsActive"

show scalar "Status" c1d2 with Status

For a browser-only control, omit both read form and the form: binding:

mutable includeBackorders = false
dash status = if includeBackorders then "Including backorders" else "Excluding backorders"

show form "Order scenario" a1b2 with
  includeBackorders mutable as "Include backorders"

show scalar "Scenario" c1d2 with status

The initial status is Excluding backorders. Ticking the checkbox changes it immediately to Including backorders. This unbound entry is not submitted as a form field and does not persist its edited value for a later run. Use read form and a form: binding, as in the preceding example, when the next run must receive the input.

A mutable variable must appear as mutable exactly once. If a mutable variable is never used with the mutable annotation, or if the same mutable variable is bound to several form entries, compilation fails.

Compile-time access

Values from read form are available at compile time and can be used to build paths in read statements. Browser-only mutable inputs cannot change those paths.

read form with
  folder : text

read "/\{folder}/orders.tsv" as T max 1m with
  Quantity : number

show scalar "Total" with sum(T.Quantity)

Enum fields and defaults

read form accepts script-defined enum types. The submitted text is interpreted as an enum label. Enums populated from data cannot be used as form input types.

A default expression must be a compile-time constant of the field’s type. For an enum field, a text label is also accepted and converted to that enum.

table enum Policy = "Standard", "Priority"
read form with
  policy : enum Policy default "Standard"
  horizon : number default 30
  startDate : date default date(2026, 1, 1)
  includeBackorders : boolean default true

show form "Planning settings" a1d4 with
  policy as "Policy"
  horizon as "Horizon (days)"
  startDate as "Start date"
  includeBackorders as "Include backorders"

With no previous submission, these fields contain Standard, 30, 2026-01-01, and true. A non-empty submitted value takes precedence over the declared default. An enum field without a default needs a submitted label, unless its enum includes the empty label "".

These defaults apply when reading the form. An expression displayed through show form with form:"name" instead controls the value offered for the next submission; it does not change the value already read for the current run.

StyleCode

For generic StyleCode rules, see stylecode.

• form tile
• entry