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:

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:

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:

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:

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:

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:

agent-native click "System Settings" --role AXRadioButton --title "Small"

---

AXPopUpButton

A dropdown menu button.

Common attributes:

• AXTitle - Button label
• AXValue - Currently selected option

Example:

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:

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:

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:

agent-native check "System Settings" --role AXSwitch --title "Wi-Fi"

---

AXLink

A clickable hyperlink.

Common attributes:

• AXTitle - Link text
• AXURL - Link destination

Example:

agent-native click Safari --role AXLink --title "Learn more"

---

AXMenuButton

A button that opens a menu.

Common attributes:

• AXTitle - Button label

Example:

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:

agent-native click Safari --role AXMenuItem --title "New Tab"

---

AXMenuBarItem

An item in the menu bar.

Common attributes:

• AXTitle - Menu bar item text

Example:

agent-native click Safari --role AXMenuBarItem --title "File"

---

AXTab

A tab in a tab group.

Common attributes:

• AXTitle - Tab label
• AXValue - Selected state

Example:

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:

agent-native fill Finder --role AXSearchField "Documents"

---

AXSecureTextField

A password input field (text is masked).

Common attributes:

• AXValue - Masked password value

Example:

agent-native fill "System Settings" --role AXSecureTextField "password123"

---

AXStepper

Increment/decrement control (up/down arrows).

Common actions:

• AXIncrement - Increase value
• AXDecrement - Decrease value

Example:

agent-native action "System Settings" @n15 AXIncrement

---

AXDisclosureTriangle

A triangle that expands/collapses content.

Common attributes:

• AXValue - 0 (collapsed) or 1 (expanded)

Example:

agent-native click Finder --role AXDisclosureTriangle

---

AXColorWell

A color picker control.

Common attributes:

• AXValue - Current color value

Example:

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:

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:

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:

agent-native tree Calculator --depth 5

Use inspect to see all attributes of a specific element:

agent-native inspect @n5

Common patterns

Finding buttons by text

agent-native find Calculator --role AXButton --title "5"

Filling text fields

agent-native fill Safari --role AXTextField "search query"

Toggling checkboxes

agent-native check "System Settings" --role AXCheckBox --title "Dark mode"

Selecting from dropdowns

# First find the popup button
agent-native snapshot "System Settings" --interactive
# Then select an option
agent-native select @n7 "Medium"

Reading static text

agent-native get text Calculator --role AXStaticText