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

To pick an element or a list of elements based on a condition at run time, add a filter inside an element node. An element with a `filter` must have a `selector` with `returnAll` set to `true`.

## Filter Properties

A `filter` object inside an element has these properties:

- `apply` (Required) String. The method called on the element, which must return a value of the type expected by `matcher`.
  - For a custom element: the method name declared inside the page object.
  - For a basic element: one of the [supported actions](/grammar/basic-actions).
- `findFirst` (Optional, default is `false`) Boolean. If `true`, returns the first element that matches the filter. If `false`, returns a list of elements. If the element is marked as `nullable`, the filter can return `null` if no match is found.
- `matcher` (Required) Object. Defines the filter criteria for the data returned by the `apply` method.
  - `type` (Required) String. The matcher type for filtering data. For supported types, see [Matchers](#matchers).
  - `args` (Optional) Array. If the matcher type requires arguments, pass them in this array.

This example uses a filter to pick one of the `lightning-menu-item` instances inside a `lightning-button-menu` based on the item text.

```json
{
  "elements": [
    {
      "name": "menuItemByText",
      "type": "utam-lightning/pageObjects/lightning/menuItem",
      "selector": {
        "css": "lightning-menu-item",
        "returnAll": true
      },
      "filter": {
        "apply": "getItemText",
        "findFirst": true,
        "matcher": {
          "type": "stringContains",
          "args": [
            {
              "name": "itemText",
              "type": "string"
            }
          ]
        }
      },
      "public": true
    }
  ]
}
```

For the example to work, the `lightning-menu-item` page object must declare a public method `getItemText` that returns menu item text.

The generated method finds all `lightning-menu-item` instances inside a `lightning-button-menu` based on the item text. For each item, `getItemText` executes and picks the first item that contains the parameter value as a substring. If no match is found, it returns null.

```java
public MenuItem getMenuItemByText(String itemText) {
    // find all available menu items
    // get text for each item
    // pick first item that contains value provided in parameter
}
```

Example of a basic element filter that returns a list:

```json
{
  "elements": [
    {
      "name": "myElement",
      "selector": {
        "css": ".myClass",
        "returnAll": true
      },
      "filter": {
        "apply": "getText",
        "matcher": {
          "type": "stringContains",
          "args": [
            {
              "name": "matcherArg",
              "type": "string"
            }
          ]
        }
      },
      "public": true
    }
  ]
}
```

UTAM generates this compiled type:

```js
getMyElement(matcherArg: string): Promise<_ActionableUtamElement[]>;
```

UTAM generates this compiled JavaScript:

```js
async getMyElement(matcherArg) {
    const driver = this.driver;
    const root = await this.getRootElement();
    let elements = await _utam_get_myElements(driver, root, );
    elements = elements.map(function _createUtamElement(element) {
        return new _ActionableUtamElement(driver, element);
    });
    const appliedFilter = await Promise.all(elements.map(el => _utam_filter_myElement(el, matcherArg)));
    elements = elements.filter((_, i) => appliedFilter[i]);
    return elements;
}
```

## Matchers

Use a matcher to apply a condition at run time:

- To pick an element or a list of elements in an element filter.
- To transform the return value of a compose statement. For an example, see [Methods](https://developer.salesforce.com/docs/platform/utam/references/utam-grammar/methods.md#matchers).

A matcher is an object with these properties.

- `type` (Required) String. The matcher type to filter data returned by an `apply` method or an element's getter method. These types are supported:
  - `isFalse` Matches `false` values.
  - `isTrue` Matches `true` values.
  - `notNull` Matches values that are not null.
  - `stringContains` Matches values containing the string passed to the matcher's `args` array.
  - `stringEquals` Matches values that equal the string passed to the matcher's `args` array.
- `args` (Optional) Array. If the matcher type requires arguments, pass them in this array.

This matcher uses the `stringContains` matcher type.

```json
"matcher": {
    "type": "stringContains",
    "args": [
        {
            "name": "itemText",
            "type": "string"
        }
    ]
}
```

## Nested elements inside filtered parent

Element with filter can have nested elements.

### Element with `findFirst` set to true (filtered element returns single element)

For example UTAM page object that has `"child"` element nested inside filtered `"parent"` that returns single element (`"findFirst": true`):

```json
{
  "name": "parent",
  "selector": {
    "css": "div",
    "returnAll": true
  },
  "filter": {
    "apply": "isVisible",
    "findFirst": true,
    "matcher": {
      "type": "isTrue"
    }
  },
  "elements": [
    {
      "name": "child",
      "selector": {
        "css": "button"
      },
      "public": true
    }
  ]
}
```

Generated code:

1. Type definition for JavaScript

```js
getChild(): Promise<_BaseUtamElement>;
```

2. Java interface

```java
BasicElement getChild();
```

### Element with `findFirst` is set to false (filtered element returns list, default)

UTAM compiler will add additional index parameter to nested element's gettter.
For example UTAM page object that has `"listField"` element nested inside filtered list `"visibleTableCells"`: true`):

```json
{
  "name": "visibleTableCells",
  "selector": {
    "css": "td",
    "returnAll": true
  },
  "filter": {
    "apply": "isVisible",
    "matcher": {
      "type": "isTrue"
    }
  },
  "elements": [
    {
      "name": "listField",
      "selector": {
        "css": "lst-template-list-field"
      },
      "type": "utam-lst/pageObjects/templateListField",
      "public": true
    }
  ]
}
```

Generated code:

1. Type definition for JavaScript

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

2. Java interface

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