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

# Targeting and selectors

> Learn how visor identifies UI elements, how selector prefixes work, and when coordinate taps are appropriate.

Selectors are used in two places:

* element-based taps
* visibility assertions

## Selector resolution

If a target string has no prefix, visor treats it as an accessibility identifier.

Example:

```text theme={null}
Increment
```

This resolves the same way as:

```text theme={null}
accessibility=Increment
```

## Supported selector prefixes

| Prefix              | Meaning                                     | Notes                                                                     |
| ------------------- | ------------------------------------------- | ------------------------------------------------------------------------- |
| `accessibility=`    | Accessibility identifier                    | Default when no prefix is present                                         |
| `id=`               | Element id                                  | Uses the driver id selector                                               |
| `text=`             | Exact text match                            | Implemented as XPath equality across multiple common text-like attributes |
| `text~=`            | Contains-style text match                   | Use when merged or multi-line semantics need substring matching           |
| `first-in-section=` | First tappable item below a section heading | Mapped execution only                                                     |
| `xpath=`            | Raw XPath                                   | Most flexible and most fragile                                            |
| `uiautomator=`      | Android UiSelector expression               | Android only                                                              |
| `predicate=`        | iOS predicate string                        | iOS only                                                                  |
| `classchain=`       | iOS class chain query                       | iOS only                                                                  |

## How `text=` works

`text=` performs an exact match against common text-like attributes.

Visor builds an XPath selector that checks whether the provided value equals any of these attributes:

* `text`
* `content-desc`
* `label`
* `name`
* `value`

Use `text~=` when you intentionally want substring matching across those same attributes. In mapped execution, broad numeric contains targets such as `text~=$100` are only treated as live/current-screen taps; they are not used to route to an off-screen destination.

## Section-relative mapped targets

Use `first-in-section=` when the request is relative to a visible section rather than a specific label.

Example:

```text theme={null}
first-in-section=Featured products
```

With mapped execution enabled, Visor routes to a screen containing that section heading and taps the first safe tappable item below it by source geometry. It skips section headings, `See all` controls, bottom navigation, back controls, static text, images, form fields, and hidden or zero-size elements.

## Choosing the right selector type

Use selectors in this order when possible:

1. accessibility identifiers
2. stable ids
3. platform-specific selectors
4. XPath
5. coordinates

This order matters because stable semantic selectors are easier to maintain and reason about.

## Coordinate taps

Coordinates are appropriate when:

* there is no reliable selector
* the target is a canvas-like region or custom-drawn control
* you need a specific screen location rather than an element

Coordinate inputs can be absolute or normalized.

| Mode       | Example                               | Meaning                                     |
| ---------- | ------------------------------------- | ------------------------------------------- |
| Absolute   | `x=120`, `y=640`                      | Raw screen coordinates                      |
| Normalized | `x=0.91`, `y=0.94`, `normalized=true` | Fraction of current screen width and height |

## Assertion targets use the same syntax

The `visible` assertion uses the same target parser as `tap`.

That means these assertion targets are valid:

* `Increment`
* `accessibility=Increment`
* `text=Checkout`
* `text~=Settings`
* `id=primary-cta`
* `xpath=//*[@text='Checkout']`
* `uiautomator=new UiSelector().text("OK")`
* `predicate=label == 'Done'`
* ``classchain=**/XCUIElementTypeButton[`label == "Done"`]``

## Known tradeoffs

Important tradeoffs in the current selector system:

* plain text defaults to accessibility ids, not visible text
* `text~=` is intentionally broad and may over-match
* `first-in-section=` needs mapped execution and source geometry for the section item
* XPath is flexible but tends to be the least stable option
* coordinate taps are sensitive to layout shifts and device differences