generative-a11y
GitHubnpm
Getting started

Getting started

Install the core and DOM packages, connect one runtime, and tell it when responses and tools change.

Install the core and browser packages

Core decides what to announce and when. DOM adds those announcements to the page. Add a framework adapter only when your app needs one.

shell
npm install @generative-a11y/core @generative-a11y/dom

How this code works

  1. 01
    Add the core runtime

    @generative-a11y/core turns app events into useful screen-reader updates and controls their timing.

  2. 02
    Add browser delivery

    @generative-a11y/dom adds those updates to the page without changing the visible interface.

Minimal integration

Create one runtime and connect it to the browser. Send only the new text from each streaming update. Report when the response finishes, fails, or stops. Dispose both resources when the session ends.

typescript
import { createGenerativeA11y } from "@generative-a11y/core";
import { connectRuntimeToDOM } from "@generative-a11y/dom";

const runtime = createGenerativeA11y({});
const delivery = connectRuntimeToDOM(runtime);

runtime.dispatch({ type: "response.started", responseId: "response-1" });
runtime.dispatch({
  type: "response.text.delta",
  responseId: "response-1",
  delta: "A complete sentence.",
});
runtime.dispatch({ type: "response.completed", responseId: "response-1" });

delivery.dispose();
runtime.dispose();

How this code works

  1. 01
    Create one runtime

    Your runtime tracks responses, prepares useful text, and controls update timing.

  2. 02
    Connect the browser

    connectRuntimeToDOM creates and manages the hidden live regions used for screen-reader updates.

  3. 03
    Report app events

    Tell the runtime when a response starts, receives text, and finishes.

  4. 04
    Clean up

    Dispose the browser connection first, then dispose the runtime when the session ends.

Choose the package that matches your app

Use a framework adapter when your app already uses that framework. For a custom app, send events directly to the core runtime.

ApplicationPackageWhat it reports
Framework-neutral@generative-a11y/core + /domAll standard library events
React@generative-a11y/reactProvider, delivery, attention, preferences
AI SDK useChat@generative-a11y/ai-sdk/reactStreaming, terminals, tools, approvals, citations
assistant-ui@generative-a11y/assistant-uiMessages, tools, approvals, sources
AG-UI / CopilotKit v2@generative-a11y/ag-uiProtocol text, tools, interrupts
Development diagnostics@generative-a11y/devtoolsRedacted runtime and DOM delivery traces
Deterministic tests@generative-a11y/testEvent recording, replay, and semantic assertions