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:60

hs.ax.focusedElement

JSValue

Fetch the focused UI element. Swift-retained storage for the JS implementation.

Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:87

hs.ax.findByRole

JSValue

Find AX elements by role. Swift-retained storage for the JS implementation.

Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:90

hs.ax.findByTitle

JSValue

Find AX elements by title. Swift-retained storage for the JS implementation.

Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:93

hs.ax.printHierarchy

JSValue

Print the element hierarchy. Swift-retained storage for the JS implementation.

Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:96

Methods

hs.ax.systemWideElement

Get the system-wide accessibility element

Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:40

Declaration

hs.ax.systemWideElement() -> HSAXElement

Parameters

None

Return Value

The system-wide AXElement, or nil if accessibility is not available

hs.ax.applicationElement

Get the accessibility element for an application

Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:46

Declaration

hs.ax.applicationElement(element) -> HSAXElement

Parameters

  • element HSApplication

    An HSApplication object

Return Value

The AXElement for the application, or nil if accessibility is not available

hs.ax.windowElement

Get the accessibility element for a window

Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:52

Declaration

hs.ax.windowElement(window) -> HSAXElement

Parameters

  • window HSWindow

    An HSWindow object

Return Value

The AXElement for the window, or nil if accessibility is not available

hs.ax.elementAtPoint

Get the accessibility element at the specific screen position

Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:57

Declaration

hs.ax.elementAtPoint(point) -> HSAXElement

Parameters

  • point HSPoint

    An HSPoint object containing screen coordinates

Return Value

The AXElement at that position, or nil if none found

hs.ax.addWatcher

Add a watcher for application AX events

Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:67

Declaration

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

Parameters

  • 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

Return Value

None

hs.ax.removeWatcher

Remove a watcher for application AX events

Hammerspoon 2/Modules/hs.ax/HSAXModule.swift:74

Declaration

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

Parameters

  • application HSApplication

    An HSApplication object

  • notification string

    The event name to stop watching

  • listener JSValue

    The function/lambda provided when adding the watcher

Return Value

None

hs.ax.focusedElement

Fetch the focused UI element

Hammerspoon 2/Modules/hs.ax/hs.ax.js:75

Declaration

hs.ax.focusedElement() -> any

Parameters

None

Return Value

An HSAXElement representing the focused UI element, or null if none was found

hs.ax.findByRole

Find AX elements for a given role

Hammerspoon 2/Modules/hs.ax/hs.ax.js:103

Declaration

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

Parameters

  • 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

Return Value

An array of found elements

hs.ax.findByTitle

Find AX elements by title

Hammerspoon 2/Modules/hs.ax/hs.ax.js:134

Declaration

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

Parameters

  • 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

Return Value

An array of found elements

hs.ax.printHierarchy

Prints the hierarchy of a given element to the Console

Hammerspoon 2/Modules/hs.ax/hs.ax.js:164

Declaration

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

Parameters

  • element any

    An HSAXElement

  • depth any

    This parameter should not be supplied

Return Value

None