Skip to main content

Selector Fields

This module is available in versions after 20260507

A selector is a Lua table that describes the UI element to find or operate on. Prefer readable text plus role, and add index only when several elements look the same.

Example​

local selector = {
    title = "Search",
    role = "text_field",
}

local item = ui_element.find(selector)

Fields​

  • title / text String. Match the element's readable title. These two fields have the same meaning.
  • text_contains String. Match a substring in the readable title.
  • value String, number, or boolean. Match the element's current value.
  • value_contains String. Match a substring in the element value.
  • identifier String. Match the element identifier. Not every app provides it.
  • bundle_id String. Match the bundle identifier of the app that owns the element.
  • role String. Match the element type. Common values include button, text_field, static_text, switch, checkbox, radio, slider, picker, scrollable, link, image, keyboard_key.
  • traits String or string array. Match trait names such as Button, StaticText, Toggle, Adjustable.
  • visible Boolean. Match whether the element is visible.
  • hittable Boolean. Match whether the element can currently be hit. Action APIs usually require the target to be hittable.
  • checked Boolean. Match confirmed state for switches, checkboxes, radio buttons, and similar controls.
  • selected Boolean. Match whether the element is selected.
  • index Integer. When multiple elements match, choose the Nth one. Index starts from 1.

Description​

Avoid using coordinates, sizes, or window identifiers as primary selectors because they are easy to change. If multiple elements match and no index is specified, action APIs may return nil, "ambiguous target". Different apps and iOS versions may expose different fields. Keep fallback logic for important missing fields.