---
schema_version: "1"
id: b701c8f9f2ec7fe120b3417f6bcc1a220a007166738c089b156f02dd43f1ea7a
title: Element Lists
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/lwc/utam/references/element-lists.md
canonical_url: https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/element-lists.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 4320914dc9d49c91692af64af0a99c4ce8b3f62af59de2e701223874e4465958
products:
  - UI Test Automation Model
  - lwc
---
# Element Lists

## Multiple elements

When a `selector` includes `"returnAll": true`, the generated method returns a list.

In the DOM, a parent can contain multiple instances of a nested element, like `lightning-tab` components inside a `lightning-tabset`. If the `selector` has a `returnAll` property set to `true`, the method returns a list of instances found at run time.

```json
{
  "elements": [
    {
      "name": "allTabs",
      "type": "utam-lightning/pageObjects/lightning/tab",
      "selector": {
        "css": "lightning-tab",
        "returnAll": true
      },
      "public": true
    }
  ]
}
```

From the previous JSON, UTAM generates this public method, which returns a list of the page objects of the given type.

```java
public List<Tab> getAllTabs() {
    // return list of instances found in runtime
    // throw exception if nothing found
}
```

## Indexes

To get one of the instances by its index, add `:nth-of-type(%d)` to the injected selector and the `args` property with an `index` parameter. `:nth-of-type(%d)` is 1-based, not 0-based.

```json
{
  "elements": [
    {
      "name": "myComponent",
      "type": "utam-lightning/pageObjects/lightning/myComponent",
      "selector": {
        "css": "lightning-my-component:nth-of-type(%d)",
        "args": [
          {
            "name": "index",
            "type": "number"
          }
        ]
      },
      "public": true
    }
  ]
}
```

The generated method finds all the custom elements inside the parent and returns one by `index`.

```java
public MyComponent getMyComponent(int index) {
    // return nth instance
    // if nothing found, or index is out of bounds, throw exception
}
```

## Elements nested inside lists

Sometimes a list element can have nested element, in the example below it's `<lst-template-list-field>` inside `<dd>`:

```html
<template for:each="{fields}" for:item="field">
  <dd key="{field.key}" class="record__card-field">
    <lst-template-list-field field="{field}"></lst-template-list-field>
  </dd>
</template>
```

The UTAM grammar allows you to include nested elements within lists:

```json
{
    "name": "recordCardField",
    "selector": {
        "css": "dd.record__card-field",
        "returnAll": true
    }
    "elements": [
        {
            "name": "listField",
            "selector": {
                "css": "lst-template-list-field"
            },
            "type": "utam-lst/pageObjects/templateListField",
            "public": true
        }
    ]
}
```

Because `"recordCardField"` is a list, the UTAM compiler will automatically generate a getter method with an index parameter in order to access the `"listField"` nested element.

Here's what the generated code might look like:

1. For JavaScript:

```javascript
/**
* @param _recordCardFieldIndex index of parent element
*/
getListField(_recordCardFieldIndex: number): Promise<(_TemplateListField)>;
```

2. For Java:

```java
/**
* @param _recordCardFieldIndex index of parent element
*/
TemplateListField getListField(_recordCardFieldIndex: integer);
```