List Formfield

A list field displays a table of rows where each row is created and edited through a dedicated subform pane (drilldown pattern). It supersedes the deprecated table field.

Key features

• Each row is edited in a full-screen subform, giving access to every field type including nested lists.
• The subform is declared as a separate top-level form of type subform and can be reused across multiple list fields in different forms (e.g. a single Address subform shared by customers, suppliers, orders…).
• Supports the same marker properties as the table field (insertMarker, updateMarker, deleteMarker) so playbook idempotency patterns still work.
• When allowDelete: false, pre-existing rows are protected; only rows added in the current session (carrying the insertMarker) can be deleted.
• The columns property controls which subform fields appear as columns in the summary table.
• The output is always an array of objects. model, noOutput, outputObject and valueColumn declared on subform fields are honoured when generating extravars.

Subform declaration

A subform is a top-level form entry with type: subform. It accepts the same fields array as any other form but is never shown in the form tile list and is never submitted directly.

forms:
  - name: Address
    type: subform
    fields:
      - name: street
        type: text
        label: Street
        required: true
      - name: city
        type: text
        label: City
        required: true
      - name: country
        type: text
        label: Country

Properties

Attribute	Comments
basic
name string / required / unique	Field name Alfanumeric + underscore + dash This attribute represents the name of the form field.
type string / required	Field type Other attributes might only be available for some field types. Value: list Examples Text - type: text name: username label: Username default: ansibleguy placeholder: type a username required: true minLength: 4 maxLength: 10 regex: expression: "^[a-zA-Z]*$" description: Must be alpha numeric icon: user help: A help message # more examples per type, check out the links at the top of the page
label string	Field label Free text A friendly name/label for the field. Note: if not set, the field name is used as label, but not when type is html. Since 6.0.3: Supports placeholders for dynamic labels (e.g., Label: $(fieldname)).
help string	Field help message Free text Some fields require additional help information. This help message will be shown below the field. Since 6.0.3: Supports placeholders for dynamic help text (e.g., This field depends on $(fieldname)).
subform string / required	Name of the subform that defines one row For a list field: delegates the per-row editor to a subform. For a yaml field: the value is a single object edited via a subform drilldown instead of a raw YAML editor. Set this property to the name of a top-level form of type subform declared in the same forms file (or in any loaded forms file). The same subform can be referenced by multiple fields, enabling reuse (e.g. a single Address subform shared across several forms).
data
default many	Default value The type of the value depends on the field type. Can be string,boolean, number, array or object. When using multiple, the default must be an array. When using an enum field, you can use the following special values : __auto__ : select the first __none__ : select none __all__ : select all (if multiple is true) For table fields, the default must be an array of objects matching the tableFields structure. For yaml fields, the default can be any valid YAML structure (object or array). For list fields, the default must be an array of objects matching the referenced subform’s fields. Use it to pre-populate the list with existing rows on form load.
expression string	A javascript expression. Valid javascript By default this javascript is evaluated on the server side and limited to predefined functions (for security). However in combination with runLocal, the evaluation is ran in the browsers sandbox and allows the full javascript power. When used in an enum field, the expression must return a flat array or array of flat objects, to make it presentable in a dropdown box. An expression supports placeholders. Read more about placeholders here. [TODO] Click here to find out more about the predefined functions. [TODO] tip : use the alias local (type=’expression’,runLocal=true,hide=true,output=false) tip : use the alias local_out (type=’expression’,runLocal=true,hide=true) tip : use the alias credential (type=’expression’,runLocal=true,hide=true,asCredential=true) Examples Get a list of users from a rest api - name: users type: enum expression: fn.fnRestBasic('get','http://myapi/user','','credential_name') Filter and sort an array of objects - name: superheros type: enum expression: | fnArray.from($(mylist)) .filterBy({has_ability:true}) .selectAttr('name','ability') .sortBy('name')" runLocal: true Make a numbered list - name: numbers type: enum expression: Array.from({length: 10}, (_, i) => i + 1) runLocal: true Use the alias `local` - name: uppercase type: local expression: "'test'.toUpperCase()" runLocal: true // this is default with type=local hide: true // this is default with type=local output: false // this is default with type=local Use the alias `local_out` - name: uppercase type: local expression: "'test'.toUpperCase()" runLocal: true // this is default with type=local hide: true // this is default with type=local
runLocal boolean	Run an expression locally When running expressions, by default they are run remotely on the server. But remote expressions are limited to predefined functions. To unleash more javascript power, use this property. The code will be evaluated in the sandbox of the browser, offloading the server, saving api-calls and making it more secure. Default: false
dbConfig string, array or object	A database connection When you want to query data from a database, you will need the proper connection information. We use a credential name to lookup the connection details. Legacy was to pass an object (name and type). Since version 5.0.2 you can just specify the name of the credential. The type is fetched from the credential itself (mysql, mssql, postgres, oracle or mongodb). In case of no type set, mysql is assumed. Additionally you can set an array of credential names, to use multiple databases with a single query. The result will be a join of the results. Doubles will not be removed automatically. Examples get information from a mysql database (legacy example - deprecated) # Old style (deprecated) - type was required separately: - name: cities type: enum dbConfig: name: CMDB_CONN type: mysql query: select name, country from cities # New style - just use the credential name: - name: cities type: enum dbConfig: CMDB_CONN query: select name, country from cities get information from a mysql database (new example) - name: cities type: enum dbConfig: CMDB_CONN # type is derived from the credential query: select name, country from cities get information from a mysql database (array example) - name: cities type: enum dbConfig: # the query will be a union of the results of the 2 databases - CMDB_CONN1 - CMDB_CONN2 query: select name, country from cities get information from a mongodb - name: user type: expression dbConfig: USER_DB_CONN query: cmdb~users~{"name":"ansibleguy"} # the query in mongodb has 3 parts, separated by ~ # database, collection and the query in valid json
query string	The query to select data from a database A valid sql query This is typically a classic SELECT statement. However, in the case of mongodb, the query is slightly different. See the examples. An expression supports placeholders. Read more about placeholders here. [TODO] Examples get information from a mysql database - name: cities type: enum dbConfig: CMDB_CONN query: select name, country from cities get information from a mongodb - name: user type: expression dbConfig: USER_DB_CONN query: cmdb~users~{"name":"ansibleguy"} # the query in mongodb has 3 parts, separated by ~ # database, collection and the query in valid json
interaction
dependencyFn string added in version 4.0.0	The dependency logical function This attribute represents the logical function between multiple dependencies. Choices: and (default) or
dependencies list / elements=object	Show/hide this field based on the values or other fields Reference to other formfields and their values Each dependency element is either an object with the following 2 attributes: name : holds the fieldname. values : a list of valid values for the referenced field. Or with the following 2 attributes: name : holds the fieldname. isValid : a boolean to check if the referenced is validated or not. Use in combination with attribute dependencyFn. Examples Show a field based on a checkbox - name: add_extra_comment label: Add extra comment ? type: checkbox - name: extra_comment type: text label: Type your extra comment dependencies: - name: add_extra_comment values: - true Show a field if another field is valid - name: code type: text regex: expression: "^[a-z]{3}$" description: Must be 3 characters lowercase required: true - name: code_uppercase type: expression runLocal: true expression: "'$(code)'.toUpperCase()" dependencies: - name: code isValid: true # new in 4.0.13 -> code_uppercase will only be shown if code is validated Show a field based on 2 fields, using the 'or' function - name: job_type label: Job type type: enum values: - IT - HR - Sales - Management - name: has_private_office type: checkbox label: Has private office ? - name: office_name type: text label: What's the name of the office dependencyFn: or dependencies: - name: job_type values: - Sales - Management - name: has_private_office values: - true - name: office_name2 type: text label: What's the name of the office dependencyFn: or dependencies: - name: "!job_type" # this will invert/negate - note the wrapping quotes!! needed for valid yaml values: - IT - HR - name: has_private_office values: - true
allowInsert boolean	Allow table/list insert A table or list can be used to modify existing data. If new data is not allowed, set this property to false. Default: true
allowDelete boolean	Allow table/list delete A table can be used to modify existing data. If you don’t was recoreds to be deleted, set this property to false. Default: true
output
output boolean added in version 6.2.0	Include field value as extravar Form fields are by default sent as extravars. Set to false to exclude a field from the extravar output. Note: noOutput: true is the deprecated equivalent — please migrate to output: false. Default: true
noOutput boolean	Do not output as extravar (deprecated) Deprecated since 6.2.0. Use output: false instead. Form fields are by default sent as extravars. If you do not want a field to be sent as extravar, set this attribute to true. Default: false
model string or array	Extravar modelling An dot-based string notation of an object, or an array of these By default, a field is sent as a root-extravar. If you want model the output of the extravars, you can specify a dot-notation of how this field should be modelled. Examples Model 2 fields together as a single object - name: diskName type: text model: disk[0].name - name: diskSize type: number model: disk[0].size # the extravars of this example will be like this : disk: - name: mydisk size: 123
deleteMarker string	Adds an additional deletemarker field When you remove a record in a table, it gets removed. When working with ansible and idempotency, the playbook never knew it got removed. You need to explicitly set the status to absent. So you can add a custom property to the deleted record, marking the record as deleted and sending it to the playbook for removal. Examples Mark delete record - type: table name: member expression: "[{firstname:'ansible',lastname:'guy'}]" deleteMarker: deleted tableFields: - name: firstname type: text icon: user - name: lastname type: text
insertMarker string	Adds an additional insertmarker field When you add a record in a table, it simply gets added. When working with ansible and idempotency, your playbook doesn’t know which records are new and which are not. You might want to explicitly run a taks on only the new records. So you can add a custom property to the inserted record, marking the record as new. Examples Mark new record - type: table name: member expression: "[{firstname:'ansible',lastname:'guy'}]" insertMarker: new tableFields: - name: firstname type: text icon: user - name: lastname type: text
updateMarker string added in version 5.1.0	Adds an additional updatemarker field In addition to the insert and delete markers, you can also add an update marker. Examples Mark updated record - type: table name: member expression: "[{firstname:'ansible',lastname:'guy'}]" updateMarker: updated tableFields: - name: firstname type: text icon: user - name: lastname type: text
security
noLog boolean added in version 2.2.3	Disable backend logging Disables logging in the backend, to hide passwords for example. Default: false Examples hide password in log - name: password type: password label: Enter password noLog: true
validation
required boolean	Required field Makes the field required. Default: false
validIf object added in version 2.2.4	An field based validation (field must be true) Enforces a validation where a referencing (expression) field must be true. This field requires an object with 2 attributes: field : The name of the referencing field description : A validation message to show when the validation is not met. (Since 5.0.1: Supports placeholders for dynamic messages) Examples Ip must be pingable validIf: field: rest_api_ping_test # an other expression field that is returning true or false description: The ip is not pingable
validIfNot object added in version 2.2.4	An field based validation (field must be false) Enforces a validation where a referencing (expression) field must be false. This field requires an object with 2 attributes: field : The name of the referencing field description : A validation message to show when the validation is not met. (Since 5.0.1: Supports placeholders for dynamic messages) Examples Check if powered off validIfNot: field: rest_api_ping_test # an other expression field that is returning true or false description: The ip is still pingable, shut down the machine first
ignoreIncomplete boolean	Allow form submit on non-evaluated placeholders When an expression-based field has placeholders, the default form behaviour is not to allow form submit until all placeholders are resolved. When this attribute is true, the form does not wait for placeholder completion for this field. Default: false
visualization
group string	The field group name Free text With this attribute you can group fields together. When all fields in a group are hidden (due to dependencies), the group is also hidden.
line string added in version 4.0.3	The field line name Free text With this attribute you can group fields in a single line together. Use together with the width parameter to set the width, if not, the width is auto.
width string added in version 4.0.3	The field width A valid Bootstrap Column width With this attribute you can set the width of a field. Use together wit the line parameter to put fields on 1 line. see https://getbootstrap.com/ Choices: col-1 col-2 col-3 col-4 col-5 col-6 col-7 col-8 col-9 col-10 col-11 col-12 Examples Name and lastname - type: text name: name label: Firstname group: login line: names - type: text name: lastname label: Lastname group: login line: names
titleAdd string	Title shown in the subform pane when adding a new row When you add a row through a list field, the subform pane shows Add <label> as subtitle. Use this property to override the subtitle (e.g. Add address).
titleEdit string	Title shown in the subform pane when editing an existing row When you edit a row through a list field, the subform pane shows Edit <label> as subtitle. Use this property to override the subtitle (e.g. Edit address).
columns array	The list of columns visible in the dropdown/table For an enum field: all properties are shown by default. Use this property to choose which columns are visible in the dropdown. For a list field: all scalar subform fields are shown by default. Use this property to pick which subform fields render as columns in the list table (missing names soft-fail and render as empty columns). Examples Show only wanted columns - name: users type: enum dbConfig: CMDB query: SELECT id, name, username, zip, city FROM users columns: - name - username

Examples

Shared address subform

forms:
  - name: Address
    type: subform
    fields:
      - name: street
        type: text
        label: Street
        required: true
      - name: city
        type: text
        label: City
        required: true
      - name: country
        type: text
        label: Country

  - name: Create customer
    type: ansible
    playbook: customer.yaml
    fields:
      - name: name
        type: text
        label: Customer name
        required: true
      - name: addresses
        type: list
        label: Addresses
        subform: Address
        columns:
          - city
          - country
        titleAdd: Add address
        titleEdit: Edit address
        allowInsert: true
        allowDelete: true

Marker tracking (idempotency-aware)

- name: people
  type: list
  label: People
  subform: Person
  allowDelete: false       # preloaded rows are protected
  insertMarker: added      # session-added rows remain removable
  updateMarker: updated
  deleteMarker: removed
  columns:
    - name
    - email

Pre-populating rows

A list can be pre-filled from three sources. In every case the produced rows must be objects whose keys match the referenced subform’s field names.

Static default

- name: addresses
  type: list
  label: Addresses
  subform: Address
  columns:
    - city
    - country
  default:
    - street: Main 1
      city: Brussels
      country: BE
    - street: Side 22
      city: Paris
      country: FR

From a REST API (expression)

- name: users
  type: list
  label: Users
  subform: User
  columns:
    - username
    - email
  expression: fn.fnRestBasic('get','https://api.example.com/users','','my_api_cred','')
  refresh: true            # add a refresh button (or '30s' for auto-refresh)

From a database query (dbConfig + query)

- name: servers
  type: list
  label: Servers
  subform: Server
  columns:
    - hostname
    - role
  dbConfig: CMDB_CONN
  query: SELECT hostname, role FROM servers WHERE active = 1

From a local expression (runLocal)

- name: ports
  type: list
  label: Open ports
  subform: Port
  columns:
    - port
    - protocol
  runLocal: true
  expression: |
    [
      { port: 22,  protocol: 'tcp' },
      { port: 80,  protocol: 'tcp' },
      { port: 443, protocol: 'tcp' }
    ]

Nested lists

forms:
  - name: Address
    type: subform
    fields:
      - name: street
        type: text
        label: Street
      - name: city
        type: text
        label: City

  - name: Person
    type: subform
    fields:
      - name: name
        type: text
        label: Name
        required: true
      - name: addresses
        type: list
        label: Addresses
        subform: Address
        columns:
          - street
          - city

  - name: My Form
    type: ansible
    playbook: people.yaml
    fields:
      - name: people
        type: list
        label: People
        subform: Person
        columns:
          - name
          - addresses

Accessing parent form data via __parent__

When a subform row editor opens, AnsibleForms automatically injects a __parent__ variable into the subform containing a snapshot of all parent form field values (including constants and vars).

Use it with the standard $(...) expression syntax in the subform’s field definitions:

forms:
  - name: NodeConfig
    type: subform
    fields:
      - name: node_name
        type: text
        label: Node name
        required: true

      - name: node_type
        type: enum
        values:
          - standard
          - high-memory
          - gpu
        # only offer gpu in production environments (parent field)
        expression: |
          '$(__parent__.environment)' === 'production'
            ? ['standard', 'high-memory', 'gpu']
            : ['standard', 'high-memory']
        runLocal: true
        default: __auto__

  - name: Deploy cluster
    type: ansible
    playbook: deploy.yml
    fields:
      - name: environment
        type: enum
        values: [dev, staging, production]
        required: true

      - name: nodes
        type: list
        subform: NodeConfig
        columns: [node_name, node_type]

__parent__ is stripped from Ansible extravars — it is a frontend-only helper. It is never sent to your playbook.