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

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 function A function called with the notification name and the accessibility 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 function 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() -> HSAXElement

Fetch the focused UI element
Declaration
hs.ax.focusedElement() -> HSAXElement
Returns
HSAXElement
An HSAXElement representing the focused UI element, or nil if none was found
Example
const el = hs.ax.focusedElement()
console.log(el.role + " " + el.title)
Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:117

hs.ax.findByRole(role, parent) -> HSAXElement[]

Find AX elements matching a given role
Declaration
hs.ax.findByRole(role, parent) -> HSAXElement[]
Parameters
Name Type Description
role string The role name to search for (e.g. "AXButton")
parent HSAXElement An HSAXElement to search within
Returns
HSAXElement[]
An array of matching HSAXElement objects
Example
const app = hs.application.frontmost()
const buttons = hs.ax.findByRole("AXButton", hs.ax.applicationElement(app))
Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:129

hs.ax.findByTitle(title, parent) -> HSAXElement[]

Find AX elements whose title contains a given string
Declaration
hs.ax.findByTitle(title, parent) -> HSAXElement[]
Parameters
Name Type Description
title string The string to search for within element titles
parent HSAXElement An HSAXElement to search within
Returns
HSAXElement[]
An array of matching HSAXElement objects
Example
const app = hs.application.frontmost()
const matches = hs.ax.findByTitle("OK", hs.ax.applicationElement(app))
Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:141

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

Print the accessibility hierarchy of an element to the Console
Declaration
hs.ax.printHierarchy(element, maxDepth) -> None
Parameters
Name Type Description
element HSAXElement An HSAXElement to print. If omitted, the system-wide element is used
maxDepth number Maximum number of levels to traverse. Defaults to 5
Returns
None
Example
const app = hs.application.frontmost()
hs.ax.printHierarchy(hs.ax.applicationElement(app), 3)
Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:152