Skip to main content

Text Element Module (ui_element)

This module is available in versions after 20260507

ui_element reads UI elements from the current screen by text, role, state, or coordinate, and performs actions such as click, scroll, text input, toggle, and adjustment on matched elements. It is useful when scripts need to understand the current UI, reduce hard-coded coordinates, or keep readable targeting logic across devices.

For fixed-coordinate touch operations, prefer the Touch Module. Coordinates exposed by ui_element are physical pixels.

Basic Usage​

local ui_element = require("ui_element")

local item, err = ui_element.find({
    title = "Search",
    role = "text_field",
})

if item then
    ui_element.input_text(item, "hello")
else
    sys.toast(err)
end

Description​

Query APIs usually return nil, err on failure. find_all returns an empty array when no element matches. Action APIs return true, info on success and nil, err on failure. After the UI changes, a previous snapshot no longer represents the latest screen. Call snapshot() again.