Skip to main content

Element Fields

This module is available in versions after 20260507

Elements returned by query APIs are plain Lua tables. Fields come from the current UI, so different apps and control types may return different fields.

Common Fields​

  • text
    String. Readable title of the element.
  • value
    Any type. Current value of the element. Text fields usually expose current text, switches may expose 0 or 1, and sliders may expose percentage text.
  • identifier
    String. Element identifier.
  • hint
    String. System hint text.
  • bundleId
    String. Bundle identifier of the app that owns the element.
  • x / y / width / height
    Integer. Element frame in physical pixels.
  • centerPoint
    Table. Element center point in physical pixels, for example { x = 100, y = 200 }.
  • children
    Table. Child element array. Expansion depth is controlled by max_level.
  • traits
    Integer. Raw trait value.
  • traitsDescription
    Table. Trait name array, such as Button, StaticText, Toggle, Adjustable.
  • isVisible
    Boolean. Whether the element is visible.
  • isSelected
    Boolean. Whether the element is selected.
  • isToggle
    Boolean. Whether the element behaves like a switch.
  • isAdjustable
    Boolean. Whether the element supports increase or decrease.
  • checked
    Boolean. Confirmed state for switches, checkboxes, radio buttons, and similar controls. It may be absent when the state cannot be read reliably.
  • hasTextEntry
    Boolean. Whether the element looks like a text input target.
  • isKeyboardKey
    Boolean. Whether the element looks like a keyboard key.
  • absoluteValue
    Number. Normalized value that may appear on adjustable controls such as sliders.

Hit State Fields​

These fields may appear only when include_hit_state, hit_test, fallback_hit_test, or an action check is used:

  • canHit
    Boolean. Whether the element can currently be hit from the top layer.
  • hitVerified
    Boolean. Whether hit state has been checked.
  • hitTestPoint
    Table. Hit point in physical pixels.

Description​

Element fields are useful for reading and checking current UI state. For stable targeting, prefer semantic fields such as text, role, checked, and selected. After the UI changes, query the element again or capture a new snapshot.