Find One UI Element (ui_element.find)

This function is available in versions after 20260507

Declaration

element, err = ui_element.find(selector [, options ])

Parameters

• selector Table. Describes the target UI element. See Selector fields.
• options Optional, table. See Common options.

Returns

• element Table. First matched UI element. nil on failure.
• err String. Failure reason. When no element matches, it is usually "target not found".

Description

If selector.index exists, the Nth matched element is returned. Prefer title or text_contains with role to reduce ambiguity.

Example

local ui_element = require("ui_element")

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

if item then
    ui_element.click(item)
else
    sys.toast(err)
end

Note: Uses non-chapter API sys.toast.