# UIHelper.waitForElement

Wait for a matching element.

```js
ui.waitForElement(selector, optionsOrTimeout?)
```

## Arguments

| Argument | Type | Meaning |
| --- | --- | --- |
| `selector` | object \| string | Attribute filters; a string means {name: string}. See the UIHelper guide for selectors. |
| `optionsOrTimeout` | object \| number | Optional milliseconds, or {timeout:5000, interval:100, throwOnTimeout:true}. Interval is at least 10 ms. |

## Returns

Element; throws TimeoutError on timeout. With throwOnTimeout:false, returns null.

## Example

```js
const ui = UIHelper.forApp("com.example.app");
const field = ui.waitForElement({id: "search", visible: true, enabled: true}, 5000);
field.setText("Hello");
```

## Notes

Replace example identifiers with selectors verified in your app. Pinning an app does not open it. Presence alone is not visibility. Communication and selector errors still throw. Global shortcuts use the unpinned foreground-app client.

## Also available as

`waitForElement`.

[All JavaScript APIs](https://mcp.applesauceos.com/doc/api.md) · [Automation playbook](https://mcp.applesauceos.com/doc/ai.md)