API Docs

hs.ax

Module

Accessibility API Module

This module provides access to macOS's powerful Accessibility API, allowing you to:

  • Inspect UI elements in any application
  • Monitor window and element changes
  • Programmatically interact with UI elements

Basic Usage

// Get the focused UI element
const element = hs.ax.focusedElement();
console.log(element.role, element.title);

// Watch for window creation events
const app = hs.application.frontmost();
hs.ax.addWatcher(app, "AXWindowCreated", (notification, element) => {
    console.log("New window:", element.title);
});

Note: Requires accessibility permissions in System Preferences.

Types

This module provides the following types:

Properties

hs.ax.notificationTypes

{[key: string]: string}
A dictionary containing all of the notification types that can be used with hs.ax.addWatcher()
Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:82

hs.ax.focusedElement

JSValue
Fetch the focused UI element. Swift-retained storage for the JS implementation.
Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:126

hs.ax.findByRole

JSValue
Find AX elements by role. Swift-retained storage for the JS implementation.
Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:134

hs.ax.findByTitle

JSValue
Find AX elements by title. Swift-retained storage for the JS implementation.
Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:142

hs.ax.printHierarchy

JSValue
Print the element hierarchy. Swift-retained storage for the JS implementation.
Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:150

Methods

hs.ax.systemWideElement() -> HSAXElement

Get the system-wide accessibility element
Declaration
hs.ax.systemWideElement() -> HSAXElement
Returns
HSAXElement
The system-wide AXElement, or nil if accessibility is not available
Example
const sys = hs.ax.systemWideElement()
Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:44

hs.ax.applicationElement(element) -> HSAXElement

Get the accessibility element for an application
Declaration
hs.ax.applicationElement(element) -> HSAXElement
Parameters
Name Type Description
element HSApplication An HSApplication object
Returns
HSAXElement
The AXElement for the application, or nil if accessibility is not available
Example
const app = hs.application.frontmost()
const ax = hs.ax.applicationElement(app)
Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:55

hs.ax.windowElement(window) -> HSAXElement

Get the accessibility element for a window
Declaration
hs.ax.windowElement(window) -> HSAXElement
Parameters
Name Type Description
window HSWindow An HSWindow object
Returns
HSAXElement
The AXElement for the window, or nil if accessibility is not available
Example
const win = hs.window.focusedWindow()
const ax = hs.ax.windowElement(win)
Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:66

hs.ax.elementAtPoint(point) -> HSAXElement

Get the accessibility element at the specific screen position
Declaration
hs.ax.elementAtPoint(point) -> HSAXElement
Parameters
Name Type Description
point HSPoint An HSPoint object containing screen coordinates
Returns
HSAXElement
The AXElement at that position, or nil if none found
Example
const el = hs.ax.elementAtPoint({x: 100, y: 200})
Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:75

hs.ax.addWatcher(application, notification, listener) -> None

Add a watcher for application AX events
Declaration
hs.ax.addWatcher(application, notification, listener) -> None
Parameters
Name Type Description
application HSApplication An HSApplication object
notification string An event name
listener JSValue A function/lambda to be called when the event is fired. The function/lambda will be called with two arguments: the name of the event, and the element it applies to
Returns
None
Example
const app = hs.application.frontmost()
hs.ax.addWatcher(app, "AXWindowCreated", (notification, element) => {
    console.log("New window:", element.title)
})
Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:96

hs.ax.removeWatcher(application, notification, listener) -> None

Remove a watcher for application AX events
Declaration
hs.ax.removeWatcher(application, notification, listener) -> None
Parameters
Name Type Description
application HSApplication An HSApplication object
notification string The event name to stop watching
listener JSValue The function/lambda provided when adding the watcher
Returns
None
Example
const app = hs.application.frontmost()
hs.ax.removeWatcher(app, "AXWindowCreated", myHandler)
Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:108

hs.ax.focusedElement() -> any

Fetch the focused UI element
Declaration
hs.ax.focusedElement() -> any
Returns
any
An HSAXElement representing the focused UI element, or null if none was found
Hammerspoon 2/Modules/hs.ax/hs.ax.js:75

hs.ax.findByRole(role, parent) -> any

Find AX elements for a given role
Declaration
hs.ax.findByRole(role, parent) -> any
Parameters
Name Type Description
role any The role name to search for
parent any An HSAXElement object to search. If none is supplied, the search will be conducted system-wide
Returns
any
An array of found elements
Hammerspoon 2/Modules/hs.ax/hs.ax.js:103

hs.ax.findByTitle(title, parent) -> any

Find AX elements by title
Declaration
hs.ax.findByTitle(title, parent) -> any
Parameters
Name Type Description
title any The name to search for
parent any An HSAXElement object to search. If none is supplied, the search will be conducted system-wide
Returns
any
An array of found elements
Hammerspoon 2/Modules/hs.ax/hs.ax.js:134

hs.ax.printHierarchy(element, depth) -> None

Prints the hierarchy of a given element to the Console
Declaration
hs.ax.printHierarchy(element, depth) -> None
Parameters
Name Type Description
element any An HSAXElement
depth any This parameter should not be supplied
Returns
None
Hammerspoon 2/Modules/hs.ax/hs.ax.js:164