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).
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
noOutput
boolean

Do not output as extravar

Form fields are by default send 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:
    name: CMDB
    type: mysql
  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

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

Copyright © 2023-2026 AnsibleForms. All rights reserved.