> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ericclemmons/agent-native/llms.txt
> Use this file to discover all available pages before exploring further.
# AX roles reference
> Complete reference of macOS Accessibility roles for element filtering
Accessibility roles identify the type and purpose of UI elements in macOS applications. Use roles to filter and target specific elements.
## What are AX roles?
Every UI element in a macOS app has an accessibility role that describes what it is. Roles are part of Apple's Accessibility API and follow the naming convention `AXRoleName`.
You can use roles with commands like `find`, `click`, and `snapshot` to target specific types of elements:
```bash theme={null}
agent-native find Safari --role AXButton
agent-native click Calculator --role AXButton --title "5"
```
## Interactive elements
These roles represent elements users can interact with.
### AXButton
A clickable button.
**Common attributes:**
* `AXTitle` - Button text
* `AXEnabled` - Whether the button is clickable
* `AXFocused` - Whether the button has focus
**Common actions:**
* `AXPress` - Click the button
**Example:**
```bash theme={null}
agent-native click Calculator --role AXButton --title "="
```
***
### AXTextField
A single-line text input field.
**Common attributes:**
* `AXValue` - Current text content
* `AXPlaceholderValue` - Placeholder text
* `AXEnabled` - Whether the field is editable
**Example:**
```bash theme={null}
agent-native fill Safari --role AXTextField "search query"
```
***
### AXTextArea
A multi-line text input area.
**Common attributes:**
* `AXValue` - Current text content
* `AXEnabled` - Whether the area is editable
* `AXNumberOfCharacters` - Character count
**Example:**
```bash theme={null}
agent-native fill TextEdit --role AXTextArea "Document content"
```
***
### AXCheckBox
A checkbox that can be checked or unchecked.
**Common attributes:**
* `AXTitle` - Checkbox label
* `AXValue` - 0 (unchecked) or 1 (checked)
* `AXEnabled` - Whether the checkbox is interactive
**Example:**
```bash theme={null}
agent-native check "System Settings" --role AXCheckBox --title "Dark mode"
```
***
### AXRadioButton
A radio button for selecting one option from a group.
**Common attributes:**
* `AXTitle` - Radio button label
* `AXValue` - 0 (unselected) or 1 (selected)
**Example:**
```bash theme={null}
agent-native click "System Settings" --role AXRadioButton --title "Small"
```
***
### AXPopUpButton
A dropdown menu button.
**Common attributes:**
* `AXTitle` - Button label
* `AXValue` - Currently selected option
**Example:**
```bash theme={null}
agent-native select "System Settings" @n7 "Medium"
```
***
### AXComboBox
A combination of a text field and dropdown.
**Common attributes:**
* `AXValue` - Current text/selection
* `AXEnabled` - Whether the combo box is interactive
**Example:**
```bash theme={null}
agent-native find Safari --role AXComboBox
```
***
### AXSlider
A slider for selecting a value from a range.
**Common attributes:**
* `AXValue` - Current slider value
* `AXMinValue` - Minimum value
* `AXMaxValue` - Maximum value
**Common actions:**
* `AXIncrement` - Increase value
* `AXDecrement` - Decrease value
**Example:**
```bash theme={null}
agent-native action "System Settings" @n12 AXIncrement
```
***
### AXSwitch
A toggle switch (common in iOS-style interfaces).
**Common attributes:**
* `AXValue` - 0 (off) or 1 (on)
* `AXTitle` - Switch label
**Example:**
```bash theme={null}
agent-native check "System Settings" --role AXSwitch --title "Wi-Fi"
```
***
### AXLink
A clickable hyperlink.
**Common attributes:**
* `AXTitle` - Link text
* `AXURL` - Link destination
**Example:**
```bash theme={null}
agent-native click Safari --role AXLink --title "Learn more"
```
***
### AXMenuButton
A button that opens a menu.
**Common attributes:**
* `AXTitle` - Button label
**Example:**
```bash theme={null}
agent-native click Finder --role AXMenuButton --title "View"
```
***
### AXMenuItem
An item within a menu.
**Common attributes:**
* `AXTitle` - Menu item text
* `AXEnabled` - Whether the item is selectable
**Example:**
```bash theme={null}
agent-native click Safari --role AXMenuItem --title "New Tab"
```
***
### AXMenuBarItem
An item in the menu bar.
**Common attributes:**
* `AXTitle` - Menu bar item text
**Example:**
```bash theme={null}
agent-native click Safari --role AXMenuBarItem --title "File"
```
***
### AXTab
A tab in a tab group.
**Common attributes:**
* `AXTitle` - Tab label
* `AXValue` - Selected state
**Example:**
```bash theme={null}
agent-native click "System Settings" --role AXTab --title "General"
```
***
### AXSearchField
A text field specifically for search input.
**Common attributes:**
* `AXValue` - Current search text
* `AXPlaceholderValue` - Placeholder text
**Example:**
```bash theme={null}
agent-native fill Finder --role AXSearchField "Documents"
```
***
### AXSecureTextField
A password input field (text is masked).
**Common attributes:**
* `AXValue` - Masked password value
**Example:**
```bash theme={null}
agent-native fill "System Settings" --role AXSecureTextField "password123"
```
***
### AXStepper
Increment/decrement control (up/down arrows).
**Common actions:**
* `AXIncrement` - Increase value
* `AXDecrement` - Decrease value
**Example:**
```bash theme={null}
agent-native action "System Settings" @n15 AXIncrement
```
***
### AXDisclosureTriangle
A triangle that expands/collapses content.
**Common attributes:**
* `AXValue` - 0 (collapsed) or 1 (expanded)
**Example:**
```bash theme={null}
agent-native click Finder --role AXDisclosureTriangle
```
***
### AXColorWell
A color picker control.
**Common attributes:**
* `AXValue` - Current color value
**Example:**
```bash theme={null}
agent-native click "System Settings" --role AXColorWell
```
## Structural elements
These roles organize and contain other elements.
### AXWindow
An application window.
**Common attributes:**
* `AXTitle` - Window title
* `AXMain` - Whether this is the main window
* `AXFocused` - Whether the window has focus
***
### AXGroup
A generic container for grouping elements.
**Common attributes:**
* `AXTitle` - Group label (if any)
* `AXDescription` - Group description
***
### AXScrollArea
A scrollable area containing content.
**Common attributes:**
* `AXChildren` - Content inside the scroll area
* `AXHorizontalScrollBar` - Horizontal scrollbar element
* `AXVerticalScrollBar` - Vertical scrollbar element
***
### AXSplitGroup
A container with resizable panes.
***
### AXToolbar
A toolbar containing buttons and controls.
**Common attributes:**
* `AXTitle` - Toolbar name
***
### AXTabGroup
A container for tabs.
**Common attributes:**
* `AXTabs` - Array of tab elements
## Display elements
These roles present information to users.
### AXStaticText
Non-editable text content.
**Common attributes:**
* `AXValue` - Text content
***
### AXImage
An image or icon.
**Common attributes:**
* `AXDescription` - Image description
* `AXTitle` - Image title
***
### AXProgressIndicator
A progress bar or spinner.
**Common attributes:**
* `AXValue` - Current progress value
* `AXMinValue` - Minimum value (usually 0)
* `AXMaxValue` - Maximum value (usually 100)
***
### AXValueIndicator
Displays a value (like a label showing a slider's value).
**Common attributes:**
* `AXValue` - The displayed value
***
### AXBusyIndicator
A loading spinner or activity indicator.
## Table and list elements
### AXTable
A table with rows and columns.
**Common attributes:**
* `AXRows` - Array of row elements
* `AXColumns` - Array of column elements
* `AXVisibleRows` - Currently visible rows
***
### AXRow
A row within a table.
**Common attributes:**
* `AXIndex` - Row index
* `AXSelected` - Whether the row is selected
***
### AXColumn
A column within a table.
**Common attributes:**
* `AXTitle` - Column header
* `AXIndex` - Column index
***
### AXCell
A cell within a table.
**Common attributes:**
* `AXValue` - Cell content
***
### AXList
A list of items.
**Common attributes:**
* `AXChildren` - List items
***
### AXOutline
A hierarchical tree/outline view.
**Common attributes:**
* `AXRows` - Outline rows
* `AXSelectedRows` - Currently selected rows
## Using roles effectively
### Combine roles with other filters
Roles are most powerful when combined with title, label, or value filters:
```bash theme={null}
agent-native find Safari --role AXButton --title "New Tab"
agent-native find TextEdit --role AXTextField --label "Find"
```
### Interactive-only snapshots
The `snapshot` command can filter to only interactive roles:
```bash theme={null}
agent-native snapshot Calculator --interactive
```
This includes:
* AXButton
* AXTextField
* AXTextArea
* AXCheckBox
* AXRadioButton
* AXPopUpButton
* AXComboBox
* AXSlider
* AXMenuButton
* AXLink
* AXTab
* AXMenuItem
* AXMenuBarItem
* AXSwitch
* AXToggle
* AXSearchField
* AXSecureTextField
* AXStepper
* AXDisclosureTriangle
* AXIncrementor
* AXColorWell
* AXSegmentedControl
### Discover roles with tree and inspect
Use the `tree` command to see all roles in an application:
```bash theme={null}
agent-native tree Calculator --depth 5
```
Use `inspect` to see all attributes of a specific element:
```bash theme={null}
agent-native inspect @n5
```
## Common patterns
```bash theme={null}
agent-native find Calculator --role AXButton --title "5"
```
```bash theme={null}
agent-native fill Safari --role AXTextField "search query"
```
```bash theme={null}
agent-native check "System Settings" --role AXCheckBox --title "Dark mode"
```
```bash theme={null}
# First find the popup button
agent-native snapshot "System Settings" --interactive
# Then select an option
agent-native select @n7 "Medium"
```
```bash theme={null}
agent-native get text Calculator --role AXStaticText
```