Accessibility

Needle Engine includes built-in accessibility support, making interactive 3D content discoverable and usable with screen readers and other assistive technology — without requiring any code changes for common use cases.

Since v4.15.0, Needle Engine automatically maintains a visually-hidden DOM overlay that mirrors your 3D scene's interactive elements with proper ARIA roles and labels. When users hover over interactive objects, the browser's live region announces them — no focus steal required.

How It Works

The AccessibilityManager creates an invisible DOM tree alongside your 3D canvas. This tree mirrors interactive objects in the scene with proper ARIA semantics, so assistive technology (like screen readers) can discover and navigate them.

• ARIA roles and labels — each interactive object gets a role and aria-label in the hidden DOM
• Live region — hovering over 3D objects announces them to the screen reader via aria-live="polite" without moving focus
• Focus API — focus() and unfocus() let you route keyboard focus to a hidden DOM element when a 3D object is activated
• No visual change — the overlay is position: absolute; width: 1px; height: 1px; clip: rect(0,0,0,0), completely invisible

Automatic Integration

The following built-in components register themselves with the AccessibilityManager automatically — no configuration needed:

If your scene uses any of these components, screen readers can already announce and navigate interactive elements out of the box.

Accessing the Manager

From any component, access the manager via this.context.accessibility:

import { Behaviour } from "@needle-tools/engine";

export class MyInteractiveObject extends Behaviour {
    onEnable() {
        // Register this object as an accessible button
        this.context.accessibility.updateElement(this.gameObject, {
            role: "button",
            label: "Spin the cube",
        });
    }

    onDisable() {
        this.context.accessibility.removeElement(this.gameObject);
    }
}

Custom Component Example

Here is a complete example of a custom interactive component that participates in the accessibility tree:

import { Behaviour, IPointerEventHandler, PointerEventData, serializable } from "@needle-tools/engine";

export class AccessiblePortal extends Behaviour implements IPointerEventHandler {

    /** Label read by screen readers */
    @serializable()
    label: string = "Enter portal";

    onEnable() {
        this.context.accessibility.updateElement(this.gameObject, {
            role: "button",
            label: this.label,
        });
    }

    onDisable() {
        this.context.accessibility.removeElement(this.gameObject);
    }

    onPointerEnter(_data: PointerEventData) {
        this.context.accessibility.hover(this.gameObject);
    }

    onPointerClick(_data: PointerEventData) {
        // ... do the portal logic
    }
}

ARIA Roles Reference

Common ARIA roles for 3D interactive objects:

For a complete list, see the WAI-ARIA roles reference.

Tips & Best Practices