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.