> ## Documentation Index
> Fetch the complete documentation index at: https://docs.optexity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Count Locator Action

> Count how many elements a Playwright locator matches on the current page

Use `misc_action.count_locator` to count Playwright locator matches on the current page and store the integer in `generated_variables`—useful for pagination checks, empty-state branches, or capping loops.

## Overview

* **Use when**: You need the match count as a variable (e.g. decide whether to paginate, skip an empty table, or compare against a threshold) without iterating over the matches.
* **Execution**: Resolves `locator` against the live page, waits for the first match to attach (optional timeout), then waits until the match count is stable for 1s before storing the result.
* **Same counting semantics as locator for-loops**: See [For Loop Node](/docs/building-automations/for-loop-node) for `locator_timeout` and the stable-count wait.

## Properties

| Property               | Type          | Default  | Description                                                                                                             |
| ---------------------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `locator`              | `str`         | Required | Playwright locator command evaluated against `page`, e.g. `get_by_role("row")`                                          |
| `name`                 | `str`         | Required | Key written into `generated_variables` as a single-element list `[count]`. Accepts placeholders (e.g. `"rows_{index}"`) |
| `locator_timeout`      | `float`       | `5.0`    | Seconds to wait for the first match to attach before counting; `0` skips the attach wait                                |
| `output_variable_name` | `str \| None` | `None`   | When set, also append the count to task `output_data` under this key. Accepts placeholders                              |

## JSON Example

```json theme={null}
{
  "type": "action_node",
  "misc_action": {
    "count_locator": {
      "locator": "get_by_role(\"row\")",
      "name": "row_count"
    }
  }
}
```

After this action, `{row_count[0]}` is available in subsequent nodes (including `if_else_node` conditions and `set_variable` expressions).

To also include the count in the task output payload, set `output_variable_name`:

```json theme={null}
{
  "misc_action": {
    "count_locator": {
      "locator": "get_by_role(\"row\")",
      "name": "row_count",
      "output_variable_name": "row_count"
    }
  }
}
```

## Waiting for Matches

Playwright's `count()` does not auto-wait. Without `locator_timeout`, an asynchronously rendered table can count as empty. Defaults match locator for-loops: wait up to 5s for the first match, then require the count to stay unchanged for 1s so streaming rows are included.

```json theme={null}
{
  "misc_action": {
    "count_locator": {
      "locator": "locator(\"table tbody tr\")",
      "name": "result_rows",
      "locator_timeout": 10.0
    }
  }
}
```

Zero matches is a valid result: the action stores `0` (with a warning) rather than failing the run.

## Count Locator vs Locator For-Loop

|             | `misc_action.count_locator`           | `for_loop_node` with `locator`                                   |
| ----------- | ------------------------------------- | ---------------------------------------------------------------- |
| Purpose     | Store match count as a variable       | Iterate once per match                                           |
| Output      | `generated_variables[name] = [count]` | Body runs `count` times; `{locator[index]}` expands to `.nth(N)` |
| Typical use | Branching, thresholds, logging        | Process every row/item                                           |

<Tip>
  Use `count_locator` when you only need the number. Use a locator for-loop when you need to act on each match.
</Tip>