list#

The list property type is used to create repeatable groups of sub-properties. Each list entry represents one row and contains its own set of fields. This is commonly used for carousels, icon grids, tabbed content, and more. Each row is stored as an object and rendered in templates using <mvt:foreach>.

`list` Definition#

{
  "type": "list",
  "code": "team_members",
  "prompt": "Team Members",
  "item_prompt": "Member",
  "list_type": "group",
  "properties": [
    {
      "code": "name",
      "prompt": "Name",
      "type": "text"
    },
    {
      "code": "photo",
      "prompt": "Photo",
      "type": "image"
    }
  ]
}

Supported Fields#

Field	Type	Required	Description
`type`	string	Yes	Must be `"list"`
`code`	string	Yes	Unique identifier for this property
`prompt`	string	Yes	Admin label shown for the entire list
`item_prompt`	string	No	Label shown for each row (e.g., “Slide”, “Item”)
`list_type`	string	Yes	Type of list. Valid options: `group`, `text`, `image`, `product`, `category`, `link`
`properties`	array	Yes	Required when `list_type` is `group`. Contains sub-properties for each row
`min_count`	number	No	Minimum number of rows
`max_count`	number	No	Maximum number of rows
`preview_property_selector`	string	No	Used for live preview targeting in admin
`visibility_conditions`	object	No	Optional logic for showing/hiding the property

Field Behavior: `list_type`#

The list_type field helps Page Builder determine the intent of the list and can affect how it is displayed or interpreted in the admin UI. While it does not affect how data is stored in l.settings:instance, it may influence UI controls or labels.

`list_type`	Behavior Description
`group`	Standard grouped fields (default).
`text`	For lists of simple text strings.
`image`	Used for image-based lists like galleries or sliders.
`productcustomfieldlookup`	Used for a product custom field list.
`color`	Used for color picker lists.
`product`	Enables product selection UI in each row.
`category`	Enables category selection UI.
`link`	Indicates each list item is a link.

You can assign any string, but only known values may alter Page Builder behavior.

Field Behavior: `min_count` and `max_count`#

The min_count and max_count fields control how many entries the user is allowed to create.

min_count: The minimum number of list items that must exist before the component can be saved. If unset, it defaults to 0.
max_count: The maximum number of rows that can be added. If unset, there is no enforced limit.

If a user attempts to delete below the min_count or add beyond the max_count, the UI will prevent the action and show a visual cue.

Example:

{
  "type": "list",
  "code": "team_members",
  "prompt": "Team Members",
  "item_prompt": "Member",
  "list_type": "group",
  "min_count": 2,
  "max_count": 5,
  "properties": [
    {
      "code": "name",
      "prompt": "Name",
      "type": "text"
    },
    {
      "code": "photo",
      "prompt": "Photo",
      "type": "image"
    }
  ]
}

This would allow users to add 2 to 5 entries and would initialize with at least 2 present when combined with default values.

`l.settings:instance` Structure#

The list property will be rendered as an array of objects inside l.settings:instance. Each entry contains key-value pairs based on the defined sub-properties.

:team_members:children[1]:photo:value=Jane+Doe
:team_members:children[1]:name:value=%2Fimages%2Fjane.jpg
:team_members:children[2]:photo:value=John+Smith
:team_members:children[2]:name:value=%2Fimages%2Fjohn.jpg

Template Usage#

To loop through each entry in a list property:

<mvt:foreach iterator="member" array="instance:team_members">
  <div class="member">
    <img src="&mvte:member:photo:value;" alt="&mvte:member:name:value;">
    <h3>&mvte:member:name:value;</h3>
  </div>
</mvt:foreach>

JavaScript Access#

List values can be accessed as a standard array in JavaScript:

<script>
  var teamMembers = l.settings.instance.team_members;

  teamMembers.forEach(function (member) {
    console.log(member.name.value);
    console.log(member.photo.value);
  });
</script>

`defaults` Definition#

A default value for a list can be defined as an array of entry objects inside the defaults object:

"defaults": {
  "team_members": [
    {
      "name": {
        "value": "Jane Doe"
      },
      "photo": {
        "value": "/images/jane.jpg"
      }
    },
    {
      "name": {
        "value": "John Smith"
      },
      "photo": {
        "value": "/images/john.jpg"
      }
    }
  ]
}

Best Practices#

Use item_prompt to clarify what each row represents for the admin.
Use min_count and max_count to enforce constraints if needed.
Choose the appropriate list_type (group, text, image, etc.) for your use case.
For structured content, always use list_type: "group" with defined properties.

list#

list Definition#

Supported Fields#

Field Behavior: list_type#

Field Behavior: min_count and max_count#

l.settings:instance Structure#