Shared field properties

Use these properties to name, label, require, or conditionally show a field. Field-specific properties, such as choices or input limits, depend on the field type.

Properties shared by fields

The properties below are shared across fields; individual field types may add type-specific properties. A calculation field accepts required, but respondents do not answer it, so required has no effect on that field.

Property	Type	Required	Default when omitted	Allowed values / range	What it does
`type`	string	yes	n/a	A field type	Selects the field type.
`name`	string	yes	n/a	At least 1 character. Use letters, digits, and underscores, starting with a letter.	Identifies the field and provides its key in submission data.
`label`	string	no	None (no question text is shown), except payment fields display “Payment Amount.”	Any text. Supports `{{field}}` piping.	Sets the main question text.
`subtext`	string	no	none	Any text. Supports `{{field}}` piping.	Adds smaller text under the label.
`input_label`	string	no	none	Any text. Supports `{{field}}` piping.	Adds small text right above the input.
`required`	boolean	no	`false`	`true`, `false`	Requires an answer before the respondent leaves the page. A required field shows `*` after its label.
`visible_if`	condition array	no	none (always shown)	See conditional logic. An empty array hides the element.	Shows the element only when the condition is true.
`hide_if`	condition array	no	none (never hidden)	See conditional logic.	Hides the element when the condition is true.

A required field with no answer blocks the page. An answer containing only spaces and an empty list both count as empty. Hidden fields skip validation, including the required check. If a field has an answer problem, the form focuses the first field with a problem and shows a message under it.

visible_if and hide_if also work on layout blocks. An element is visible when visible_if is true or absent and hide_if is false. A true hide_if hides it even when visible_if is true.

Field names can use letters, digits, and underscores, starting with a letter. Names containing hyphens can be used in formulas but cannot be piped into text. Duplicate names are allowed in the config; on save and publish, later duplicates get unique names unless a condition references that name, in which case each copy keeps it.

The label, subtext, and input_label properties support {{field}} piping, which inserts another field’s answer. If there is no answer, piping uses the hidden field with the same name, then an empty string. Array answers appear as comma-separated values.

Conditions use arrays that alternate condition objects with "AND" or "OR". Nested arrays group expressions. Evaluation proceeds left to right without operator precedence, so A OR B AND C means (A OR B) AND C. The equals operator uses strict equality without type conversion, so "7" does not equal 7.

A field’s answer usually appears in submission data under its name. Matrix answers use flat keys in the form "<name>.<rowId>".

Example

This form asks for a company name only when the respondent selects the Business account type:

{
  "pages": [
    {
      "type": "form",
      "id": "p1",
      "ui": [
        {
          "type": "multiple_choice",
          "name": "account_type",
          "label": "What type of account do you need?",
          "options": ["Personal", "Business"],
          "required": true
        },
        {
          "type": "short_text_input",
          "name": "company_name",
          "label": "What is your company called?",
          "subtext": "Use the legal name, {{account_type}}.",
          "input_label": "Company",
          "required": true,
          "visible_if": [
            { "field": "account_type", "operator": "equals", "value": "Business" }
          ]
        }
      ]
    }
  ]
}

For a hosted form, a text field’s answer appears in submission data under its name:

{
  "account_type": "Business",
  "company_name": "Acme"
}