> ## 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.