Skip to main content
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"
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

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

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

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

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

agent-native get text Calculator --role AXStaticText

Build docs developers (and LLMs) love

Get started for freeTalk to us