Unity Accessibility

Unity Accessibility

Retrieval Sources

All 90 Accessibility.* ScriptReference pages plus the 7 Manual accessibility pages and the 2 PlayerLoop insertion-point pages above were re-verified on disk under /media/artiq/FRESH_DRIVE/Books/Unity6/Documentation/en/ as part of this pass; nothing in this table is inferred from memory alone.

Key Guidelines

AccessibilityHierarchy & Node Trees

The AccessibilityHierarchy is a separate data model that runs in parallel to your scene/UI hierarchy, not a reflection of it — screen readers cannot see GameObjects, VisualElements, or RectTransforms directly, only the tree of AccessibilityNodes you build and publish. A node's position in this tree (its parent/children, and its rank among rootNodes) determines screen-reader focus order and grouping; some platforms traverse depth-first through children before siblings, others use on-screen position (frame). Because nested structures are harder to navigate by voice, the module-architecture doc explicitly recommends flattening the hierarchy where possible. Build the hierarchy with AddNode/InsertNode, prune it with RemoveNode/Clear, and reparent/reorder with MoveNode — but treat MoveNode and reassigning AssistiveSupport.activeHierarchy as expensive operations on iOS/macOS when done against the active hierarchy, since Unity must rebuild native accessibility objects; batch structural changes rather than performing them one at a time on the live tree.

using UnityEngine;
using UnityEngine.Accessibility;

public class MenuAccessibilityBuilder : MonoBehaviour
{
    AccessibilityHierarchy m_Hierarchy;

    void BuildMenuHierarchy()
    {
        m_Hierarchy = new AccessibilityHierarchy();

        // Root container groups the whole panel.
        AccessibilityNode panelNode = m_Hierarchy.AddNode("Main Menu", parent: null);
        panelNode.role = AccessibilityRole.Container;

        // Child nodes under the panel — order here drives read order.
        AccessibilityNode startNode = m_Hierarchy.AddNode("Start Game", panelNode);
        startNode.role = AccessibilityRole.Button;

        AccessibilityNode settingsNode = m_Hierarchy.AddNode("Settings", panelNode);
        settingsNode.role = AccessibilityRole.Button;

        // Insert a node at a specific position instead of appending.
        AccessibilityNode quitNode = m_Hierarchy.InsertNode(0, "Quit", panelNode);
        quitNode.role = AccessibilityRole.Button;

        // Find the lowest common ancestor of two nodes, e.g. for focus management.
        AccessibilityNode commonAncestor =
            m_Hierarchy.GetLowestCommonAncestor(startNode, settingsNode); // panelNode
    }
}

AssistiveSupport & Screen Reader Detection

AssistiveSupport is the single entry point that connects your hierarchy to the OS: check AssistiveSupport.isScreenReaderEnabled to know whether assistive tech is active right now, and subscribe to AssistiveSupport.screenReaderStatusChanged to react the moment the user turns it on or off — build/refresh and assign your hierarchy in that handler rather than eagerly at startup, since Unity discards the active hierarchy whenever the screen reader is off (to save resources) and resets activeHierarchy to null automatically. Setting AssistiveSupport.activeHierarchy only takes effect while isScreenReaderEnabled is true; you must re-set it every time the screen reader is (re-)enabled, not just once. Use AssistiveSupport.nodeFocusChanged if you need to know which node the screen reader is currently on (e.g., to sync a visual focus highlight).

using UnityEngine;
using UnityEngine.Accessibility;

public class ScreenReaderGate : MonoBehaviour
{
    AccessibilityHierarchy m_Hierarchy;

    void OnEnable()
    {
        AssistiveSupport.screenReaderStatusChanged += OnScreenReaderStatusChanged;
        // Handle the case where a screen reader is already on when this object enables.
        if (AssistiveSupport.isScreenReaderEnabled)
            OnScreenReaderStatusChanged(true);
    }

    void OnDisable()
    {
        AssistiveSupport.screenReaderStatusChanged -= OnScreenReaderStatusChanged;
    }

    void OnScreenReaderStatusChanged(bool enabled)
    {
        if (enabled)
        {
            m_Hierarchy ??= BuildHierarchy();
            AssistiveSupport.activeHierarchy = m_Hierarchy; // publish it
        }
        // No need to explicitly clear activeHierarchy on disable — Unity does it.
    }

    AccessibilityHierarchy BuildHierarchy() => new AccessibilityHierarchy();
}

Labeling & Roles for Screen Readers

Every node needs a meaningful label (what the element is) and, where relevant, a value (its current state, such as a slider's number or a toggle's on/off), a hint (what happens if the user activates it), a role (AccessibilityRole.Button, .Toggle, .Header, .Slider, .StaticText, .TextField, .SearchField, .Dropdown, .TabBar/.TabButton, .KeyboardKey, .ScrollView, .Container, .Image, …), and a state (AccessibilityState.Disabled, .Selected, .Expanded, or .None). Generic or empty labels ("Button", "Image", "") are the single most common real-world screen-reader complaint — they leave the user with no idea what the control does. If nothing in AccessibilityRole fits, fall back to AccessibilityRole.None and put the missing semantic information into label/hint instead of leaving the role unset carelessly. Respond to the node's invoked (activate), incremented/decremented (steppers/sliders), dismissed, and scrolled events — do not use the deprecated selected event, which the docs explicitly say to replace with invoked.

using UnityEngine.Accessibility;

void ConfigureVolumeSlider(AccessibilityHierarchy hierarchy, AccessibilityNode parent, int currentVolume)
{
    AccessibilityNode sliderNode = hierarchy.AddNode("Master Volume", parent);
    sliderNode.role = AccessibilityRole.Slider;
    sliderNode.value = $"{currentVolume}%";
    sliderNode.hint = "Adjusts the overall game volume";
    sliderNode.state = currentVolume == 0 ? AccessibilityState.None : AccessibilityState.None;

    sliderNode.incremented += () => SetVolume(currentVolume + 10);
    sliderNode.decremented += () => SetVolume(currentVolume - 10);
    sliderNode.invoked    += () => ToggleMute();
}

Integrating with UI Toolkit/uGUI Widgets

The screen-reader APIs are UI-framework-agnostic — they work identically with UI Toolkit, uGUI, a custom framework, or non-UI 2D/3D world objects — because nodes are independent of any visual element's lifecycle. That independence cuts both ways: Unity does not auto-populate nodes for your widgets, and a node's frame/label/state will silently drift out of sync with the widget it represents unless you explicitly keep them updated. The standard pattern (per the official get-started walkthrough) is: create one AccessibilityNode per interactive/informative visual element, track the widget's GeometryChangedEvent (UI Toolkit) or its RectTransform/layout changes (uGUI) to recompute frame in screen coordinates (worldBound.position * scaledPixelsPerPoint, or equivalent), and wire the node's invoked event to the same code path the widget's own click/submit handler uses. For elements with a role that has no matching built-in VisualElement (custom controls used in UXML/UI Builder), the AccessibilityRole reference page has a worked example of authoring a custom control with the correct role assigned directly.

using UnityEngine;
using UnityEngine.Accessibility;
using UnityEngine.UIElements;

public class AccessibleStartMenu : MonoBehaviour
{
    Button m_Button;
    AccessibilityHierarchy m_AccessibilityHierarchy;
    AccessibilityNode m_AccessibilityNode;

    void OnEnable()
    {
        VisualElement root = GetComponent<UIDocument>().rootVisualElement;
        m_Button = root.Q<Button>("startButton");
        m_Button.clicked += OnButtonClicked;
        m_Button.RegisterCallback<GeometryChangedEvent>(OnGeometryChanged);

        CreateAccessibilityHierarchy();
    }

    void OnDisable()
    {
        m_Button.clicked -= OnButtonClicked;
        m_Button.UnregisterCallback<GeometryChangedEvent>(OnGeometryChanged);
    }

    void CreateAccessibilityHierarchy()
    {
        m_AccessibilityHierarchy = new AccessibilityHierarchy();
        m_AccessibilityNode = m_AccessibilityHierarchy.AddNode(m_Button.text);
        m_AccessibilityNode.role = AccessibilityRole.Button;
        m_AccessibilityNode.state = m_Button.enabledSelf
            ? AccessibilityState.None
            : AccessibilityState.Disabled;
        // Route the screen reader's "activate" gesture to the same handler as a real tap.
        m_AccessibilityNode.invoked += () =>
            m_Button.SendEvent(NavigationSubmitEvent.GetPooled());
    }

    void OnGeometryChanged(GeometryChangedEvent evt)
    {
        Rect worldRect = m_Button.worldBound;
        float scale = m_Button.panel.scaledPixelsPerPoint;
        m_AccessibilityNode.frame = new Rect(worldRect.position * scale, worldRect.size * scale);
    }

    void OnButtonClicked() => Debug.Log("Start Game button clicked");
}

Testing with Platform Screen Readers

This is a runtime-platform feature — it drives the actual OS screen reader (VoiceOver on iOS/macOS, TalkBack on Android, Narrator on Windows) inside a built Player — and is distinct from Unity Editor UX/accessibility. Use AssistiveSupport.screenReaderStatusOverride (values OSDriven, ForceEnabled, ForceDisabled) to force isScreenReaderEnabled to a known value in the Editor or a development Player when no real assistive device is attached, so your screenReaderStatusChanged handler and hierarchy-build path can be exercised without a physical accessibility session. That said, override testing is a smoke test, not a substitute for the real thing: gesture sets differ per platform (see Advanced Notes), and only an on-device VoiceOver/TalkBack/Narrator session exercises the actual native traversal, announcement timing, and gesture mapping. Unity also ships a built-in inspector for this: Window > Accessibility > Hierarchy Viewer lets you inspect live AccessibilityNode properties (label, role, state, frame) in Play Mode without leaving the Editor, which is the fastest way to catch structural mistakes before an on-device pass.

using UnityEngine.Accessibility;

#if UNITY_EDITOR
public static class AccessibilityTestUtility
{
    public static void ForceScreenReaderForTesting(bool enabled)
    {
        AssistiveSupport.screenReaderStatusOverride = enabled
            ? AssistiveSupport.ScreenReaderStatusOverride.ForceEnabled
            : AssistiveSupport.ScreenReaderStatusOverride.ForceDisabled;
    }

    public static void RestoreOSDrivenStatus()
    {
        AssistiveSupport.screenReaderStatusOverride =
            AssistiveSupport.ScreenReaderStatusOverride.OSDriven;
    }
}
#endif

Broader Accessibility Practices (beyond the API)

Screen-reader support is only one axis of accessibility. AccessibilitySettings mirrors OS-level preferences — fontScale, isBoldTextEnabled, isClosedCaptioningEnabled (Android and iOS only; unsupported on macOS/Windows Player) — so read these at startup and react to their *Changed events instead of hardcoding fixed font sizes or ignoring OS caption preferences. VisionUtility.GetColorBlindSafePalette returns a palette distinguishable under normal vision, deuteranopia, protanopia, and tritanopia — use it for any UI or gameplay signal (team colors, status indicators, minimap markers) that currently relies on hue alone, and pair it with contrast-conscious design and non-color redundant cues (icons, patterns, text). Beyond what any Unity API covers directly: ensure adequate color contrast ratios, make font/UI scale respect fontScale rather than fixed pixel sizes, and provide input remapping / alternative control schemes for players who cannot use the default scheme — these matter for players who are not screen-reader users at all, and a project can pass every screen-reader checklist item while still being inaccessible on these other axes.

using UnityEngine;
using UnityEngine.Accessibility;

public class AccessibilityPreferencesSync : MonoBehaviour
{
    void OnEnable()
    {
        ApplyFontScale(AccessibilitySettings.fontScale);
        AccessibilitySettings.fontScaleChanged += ApplyFontScale;
        AccessibilitySettings.closedCaptioningStatusChanged += ApplyCaptionPreference;
    }

    void OnDisable()
    {
        AccessibilitySettings.fontScaleChanged -= ApplyFontScale;
        AccessibilitySettings.closedCaptioningStatusChanged -= ApplyCaptionPreference;
    }

    void ApplyFontScale(float scale) { /* scale UI Toolkit root's font-size or uGUI CanvasScaler */ }
    void ApplyCaptionPreference(bool enabled) { /* show/hide subtitle track */ }

    Color[] GetTeamColors(int count) =>
        VisionUtility.GetColorBlindSafePalette(count, minHueDistance: 0f, minSaturationDistance: 0f);
}

Common Mistakes

Quick Reference

Advanced Notes

Platform differences (VoiceOver vs. TalkBack vs. Narrator). The Accessibility module is a platform-abstraction layer: you write one hierarchy and one set of node properties, and Unity translates them to each OS's native accessibility tree — but the docs are explicit that "these APIs might result in slight behavior differences across platforms," always in the direction of matching each platform's own native conventions rather than being identical everywhere. Concretely:

• VoiceOver (iOS/iPadOS, macOS) uses swipe-based gesture navigation (swipe right/left to move focus forward/back through the hierarchy, double-tap to activate — mapped to invoked — swipe up/down for incremented/decremented on sliders/steppers) and generally favors a depth-first traversal of the node tree. iOS is also where AccessibilityHierarchy.MoveNode and reassigning AssistiveSupport.activeHierarchy are documented as having their highest native cost, scaling with subtree/hierarchy size — minimize structural churn on the active hierarchy specifically on this platform. SendAnnouncement is documented to silently no-op when called from inside an iOS button's own callback.
• TalkBack (Android, API 26+/Android 8.0+) uses a comparable but distinct swipe/explore-by-touch gesture set and reads label/value/hint/role/state through Android's AccessibilityNodeInfo equivalent. Android is the only other platform (besides iOS) where AccessibilitySettings (font scale, bold text, closed captioning) actually returns live OS values — macOS and Windows Players do not support AccessibilitySettings at all, only AssistiveSupport/hierarchy features.
• Narrator (Windows) and VoiceOver (macOS) are supported by AssistiveSupport/AccessibilityHierarchy per the class docs' platform list, but AccessibilitySettings has no effect there — plan font-scale/caption/bold-text handling as mobile-only behavior, with desktop platforms needing their own settings UI if you want equivalent user control.
• Regardless of platform, gestures vary but all map to the same underlying node events (invoked, dismissed, scrolled, incremented, decremented) — this is the entire point of the abstraction: you never branch your gameplay code on Application.platform to handle accessibility interaction, only to decide whether to read AccessibilitySettings (mobile) at all.

How the Accessibility Hierarchy relates to the visual UI tree. The two trees are deliberately decoupled: an AccessibilityNode "exists and functions independently of its corresponding visual elements," per the AccessibilityNode class docs — hiding, reordering, or restyling a VisualElement/RectTransform does not automatically change the visibility, position, or content of the node that represents it. This is why every one of the worked examples above wires explicit synchronization: GeometryChangedEvent → frame updates, enabledSelf/interactable state → AccessibilityNode.state, and widget click handlers ↔ invoked. Practical consequences:

• A node with isActive = true but a frame that was never updated to match its widget's current position will report a stale hit-target to the screen reader (relevant on platforms that use frame-based rather than pure tree-order navigation).
• Destroying/hiding a VisualElement without also calling RemoveNode (or setting isActive = false) leaves a "ghost" node in the hierarchy that a screen reader can still focus on even though nothing is visually there.
• The accessibility tree can be shallower or differently shaped than the visual tree by design — the architecture doc recommends flattening it for navigability, so a deeply nested UI Toolkit/uGUI layout should often collapse to a flatter accessibility structure (e.g., group a whole card into one Container node with a synthesized label rather than exposing every internal decorative child).
• Because the accessibility hierarchy is UI-framework-agnostic, the same mechanism covers pure 3D/2D world objects with no UI representation at all (e.g., an interactable object in the game world) — you build a node for it exactly as you would for a UI Toolkit button, there's just no VisualElement on the other end to keep in sync.
• Only the hierarchy attached to the application's main window is exposed to screen readers; content on secondary displays/windows has no accessibility representation regardless of how its visual tree is structured.