/pixijs-accessibility

name: pixijs-accessibility
description: "Use this skill when adding screen reader and keyboard navigation to PixiJS v8 apps. Covers AccessibilitySystem options (enabledByDefault, debug, activateOnTab, deactivateOnMouseMove), per-container accessibility properties, shadow DOM overlay, mobile touch-hook activation. Triggers on: accessibility, a11y, screen reader, ARIA, keyboard navigation, tab order, AccessibilitySystem, accessibleTitle, accessibleHint, tabIndex, accessibleChildren."
license: MIT

Enable screen reader and keyboard navigation via PixiJS's AccessibilitySystem. The system creates an invisible shadow DOM overlay positioned over accessible containers so assistive technology can discover and activate them.

Quick Start

const button = new Sprite(await Assets.load("button.png"));
button.accessible = true;
button.accessibleTitle = "Play game";
button.accessibleHint = "Starts a new game session";
button.eventMode = "static";
button.tabIndex = 0;
app.stage.addChild(button);

app.renderer.accessibility.setAccessibilityEnabled(true);

button.on("pointertap", () => startGame());

**Related skills:** `pixijs-events` (pointer/tap handlers), `pixijs-scene-dom-container` (HTML elements on canvas), `pixijs-application` (init options).

**Key points:**

• By default the system activates only after the user presses Tab. Set `enabledByDefault: true` in Application init for immediate activation.
• On mobile, the system creates a hidden touch hook; screen-reader focus activates accessibility for the whole session.
• The AccessibilitySystem requires the main thread; it is not available in a Web Worker.

Core Patterns

Container accessible properties

import { Container, Sprite } from "pixi.js";

const container = new Container();
container.accessible = true;
container.accessibleTitle = "Navigation menu";
container.accessibleHint = "Contains links to other pages";
container.eventMode = "static"; // required for custom tabIndex to apply
container.tabIndex = 0;
container.accessibleType = "div"; // defaults to 'button'

const sprite = new Sprite();
sprite.accessible = true;
sprite.accessibleTitle = "Close dialog";
sprite.accessibleText = "X"; // text content of the shadow div
sprite.eventMode = "static";
sprite.tabIndex = 1;

Available properties on any Container:

• `accessible` (boolean) - enables the accessible overlay div
• `accessibleTitle` (string) - sets the `title` attribute on the shadow div
• `accessibleHint` (string) - sets the `aria-label` attribute
• `accessibleText` (string) - sets inner text content of the shadow div
• `accessibleType` (string) - HTML tag for the shadow element, defaults to `'button'`
• `tabIndex` (number) - tab order for keyboard navigation (only applied when `interactive` is true / `eventMode` is `'static'` or `'dynamic'`)
• `accessibleChildren` (boolean, default `true`) - when `false`, prevents child containers from being accessible
• `accessiblePointerEvents` (string) - CSS `pointer-events` value on the shadow div

Custom tab order

Give each accessible container a `tabIndex` to control the order assistive tech walks through them. Higher numbers come later; equal numbers fall back to scene-graph order.

menuButton.accessible = true;
menuButton.eventMode = "static";
menuButton.tabIndex = 1;

playButton.accessible = true;
playButton.eventMode = "static";
playButton.tabIndex = 2;

settingsButton.accessible = true;
settingsButton.eventMode = "static";
settingsButton.tabIndex = 3;

`tabIndex` is only forwarded to the shadow div when the container is `interactive` (`eventMode` is `'static'` or `'dynamic'`). Without that, the system clamps the div's tabIndex back to `0`, and the order you set is ignored.

Programmatic control

import { Application } from "pixi.js";

const app = new Application();
await app.init({ width: 800, height: 600 });

// Enable accessibility at runtime
app.renderer.accessibility.setAccessibilityEnabled(true);

// Check current state
console.log(app.renderer.accessibility.isActive);
console.log(app.renderer.accessibility.isMobileAccessibility);

// Full init options:
await app.init({
  accessibilityOptions: {
    enabledByDefault: true, // activate immediately (default: false)
    debug: true, // makes overlay divs visible (default: false)
    activateOnTab: true, // Tab key activates system (default: true)
    deactivateOnMouseMove: false, // stay active when mouse moves (default: true)
  },
});

The system can also be configured via static defaults before creating the Application:

import { AccessibilitySystem, Application } from "pixi.js";

AccessibilitySystem.defaultOptions.enabledByDefault = true;
AccessibilitySystem.defaultOptions.deactivateOnMouseMove = false;

const app = new Application();
await app.init();

Handling accessible interactions

import { Sprite } from "pixi.js";

const button = new Sprite();
button.eventMode = "static";
button.accessible = true;
button.accessibleTitle = "Submit form";
button.tabIndex = 0;

// Screen readers trigger click/tap events through the shadow DOM element
button.on("pointertap", () => {
  submitForm();
});

When accessibility is active and a user activates a shadow div (via Enter/Space key or screen reader action), the system dispatches `click`, `pointertap`, and `tap` FederatedEvents to the corresponding container. Focus on the shadow div dispatches `mouseover`, and focus-out dispatches `mouseout`. Both `eventMode` and `accessible` should be set for full keyboard + pointer support.

Common Mistakes

[MEDIUM] Expecting accessibility to be active without Tab key press

The AccessibilitySystem does not create its DOM overlay until the user presses Tab (or, on mobile, focuses the touch hook). If your application needs accessibility immediately:

const app = new Application();
await app.init({
  accessibilityOptions: {
    enabledByDefault: true,
  },
});

Or at runtime:

app.renderer.accessibilit