Crate axuielement 

axuielement

Safe Rust bindings for Apple’s AXUIElement Accessibility API on macOS.

Status: v0.9 adds an optional executor-agnostic async_api module for AXObserver notifications while keeping the Wave-C Swift bridge over the C Accessibility APIs and coverage across the crate’s ten logical areas: AXUIElement, AXObserver, AXValue, AXTextMarker, AXAttribute, AXAction, AXNotification, AXError, SystemWide, and ProcessTrust.

Quick start

use axuielement::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let Some(system) = system_wide() else {
        eprintln!("no system-wide accessibility object");
        return Ok(());
    };

    println!("api_enabled = {}", api_enabled());
    println!("is_trusted  = {}", is_process_trusted());

    if let Some(app) = system.focused_application()? {
        println!("focused pid   = {}", app.pid()?);
        println!("focused attrs = {:?}", app.attribute_names()?);
    }

    if let Some(focused) = system.focused_ui_element()? {
        println!("role  = {:?}", focused.string_attribute(axuielement::ax_attribute::AX_ROLE_ATTRIBUTE)?);
        println!("title = {:?}", focused.string_attribute(axuielement::ax_attribute::AX_TITLE_ATTRIBUTE)?);
        println!("actions = {:?}", focused.action_names()?);
    }

    Ok(())
}

Covered areas

• AXUIElement creation, attribute reads/writes, hit-testing, batch fetches, parameterized attributes, action metadata, and keyboard-event shims.
• AXObserver creation, add/remove notification registration, run-loop scheduling, info-dictionary callbacks, and async_api::AXNotificationStream.
• AXValue round-tripping for strings, booleans, numbers, CGPoint, CGSize, CGRect, CFRange, AXError, arrays, dictionaries, and binary payloads.
• AXTextMarker and AXTextMarkerRange creation plus byte round-trips.
• Generated constant modules for attributes, actions, notifications, roles, subroles, menu-item modifiers, and value constants.
• SystemWideElement convenience helpers for focused application/window/UI-element lookups.
• ProcessTrust helpers for API-enabled checks and trust queries.

See COVERAGE.md for the audited SDK surface.

Raw FFI

The original raw C declarations remain available behind the raw-ffi Cargo feature:

axuielement = { version = "0.9", default-features = false }
# or keep the default `raw-ffi` feature enabled for `axuielement::ffi`

The safe API always talks to the Swift bridge. The raw-ffi feature exists for direct low-level interop and compatibility.

Permissions

Most runtime messaging requires Accessibility permission (System Settings → Privacy & Security → Accessibility). Without it, many calls return AXError::APIDisabled or AXError::CannotComplete.

Async notifications

Enable the async Cargo feature to use axuielement::async_api::AXNotificationStream, which wraps AXObserver notifications in an executor-agnostic bounded async stream.

axuielement = { version = "0.9", features = ["async"] }

Examples and tests

• examples/01_axuielement_basic.rs
• examples/02_axobserver_basic.rs
• examples/03_axvalue_roundtrip.rs
• examples/04_axtextmarker_roundtrip.rs
• examples/05_axattribute_catalog.rs
• examples/06_axaction_catalog.rs
• examples/07_axnotification_catalog.rs
• examples/08_axerror_catalog.rs
• examples/09_system_wide_snapshot.rs
• examples/10_process_trust_status.rs
• examples/11_async_notification_stream.rs (requires --features async)

The test suite includes one smoke file per logical area plus the raw-FFI coverage harness.

License

Licensed under either Apache-2.0 or MIT at your option.

---

API documentation

Safe Rust bindings for Apple’s AXUIElement Accessibility API on macOS — read attributes, list children, perform actions, work with text markers, and subscribe to notifications on other applications’ UIs.

Re-exports

pub use ax_error::AXError;

pub use ax_notification::AXPriority;

pub use ax_observer::run_current_run_loop;

pub use ax_observer::stop_current_run_loop;

pub use ax_observer::AXObserver;

pub use ax_observer::AXObserverEvent;

pub use ax_text_marker::AXTextMarker;

pub use ax_text_marker::AXTextMarkerRange;

pub use ax_ui_element::AXCopyMultipleAttributeOptions;

pub use ax_ui_element::AXElement;

pub use ax_ui_element::AXUIElement;

pub use ax_value::AXPoint;

pub use ax_value::AXRange;

pub use ax_value::AXRect;

pub use ax_value::AXSize;

pub use ax_value::AXValue;

pub use ax_value::AXValueKind;

pub use process_trust::api_enabled;

pub use process_trust::is_process_trusted;

pub use process_trust::is_process_trusted_with_options;

pub use process_trust::is_process_trusted_with_prompt;

pub use process_trust::make_process_trusted;

pub use process_trust::ProcessTrustOptions;

pub use system_wide::system_wide;

pub use system_wide::SystemWideElement;

Modules

async_apiasync

Executor-agnostic async streams for Accessibility notifications.

ax_action

Standard Accessibility action constants.

ax_attribute

Accessibility attribute, role, subrole, and value constants.

ax_error

Errors returned by the axuielement crate.

ax_notification

Accessibility notification constants and priorities.

ax_observer

AXObserver notification support.

ax_text_marker

Safe wrappers for AXTextMarker and AXTextMarkerRange.

ax_ui_element

Safe wrapper for AXUIElement.

ax_value

Generic Accessibility values plus typed geometry helpers.

element

Compatibility shim re-exporting the v0.6 element APIs.

error

Compatibility shim re-exporting the v0.6 AXError module.

ffiraw-ffi

Raw FFI declarations for AXUIElement (Apple’s Accessibility API).

observer

Compatibility shim re-exporting the v0.6 observer APIs.

prelude

Common imports.

process_trust

Accessibility process-trust helpers.

system_wide

System-wide Accessibility helpers.