charlotte_find
Search for page elements using filters like text, role, type, proximity, or CSS selector, and receive stable element IDs for automating interactions.
Instructions
Search for elements matching criteria. Filters interactive elements by text, role, type, or spatial proximity. Use the selector parameter to find DOM elements by CSS selector — this reaches elements not in the accessibility tree (custom widgets, non-semantic divs). Selector results return Charlotte element IDs usable with click, hover, drag, etc.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| near | No | Element ID — find elements spatially near this one (within ~200px) | |
| role | No | ARIA role filter | |
| text | No | Text content to search for (case-insensitive substring match) | |
| type | No | Interactive element type filter (button, link, text_input, select, checkbox, etc.) | |
| within | No | Element ID — find elements geometrically contained within this one's bounds | |
| selector | No | CSS selector to query the DOM directly. Returns elements that may not be in the accessibility tree. Results include durable Charlotte element IDs (dom-…) that remain valid across subsequent renders and interactions, and work with fill_form; they are re-resolved against the live DOM by re-running the selector. | |
| output_file | No | Write the full match results to this file path instead of returning them inline. Relative paths resolve against output_dir (see charlotte_configure). Returns only a confirmation with the file path and size. Use for broad selectors (e.g. 'div', '*') that match many elements. |