Getting started
Choose an integration
Choose the smallest package that connects generative-a11y to your app.
Start with the framework your app uses
Choose an adapter based on the framework in your code, not the way the interface looks. An adapter can only report events the framework makes publicly available.
| Your app | Install | Choose when | Events available |
|---|---|---|---|
| Custom JavaScript | core + dom | Your app already knows when work starts and finishes | All standard library events |
| React application | react | You want a provider, browser updates, preferences, and element bindings | Events sent by your app |
| AI SDK useChat | ai-sdk + core | Your UI uses public useChat state and callbacks | Responses, tools, approvals, sources, and final response states |
| assistant-ui | assistant-ui + core | Your app exposes a public ThreadRuntime | Messages, tools, approvals, sources, and final response states |
| AG-UI or CopilotKit v2 | ag-ui + core | Your agent exposes documented protocol callbacks | Response text, tools, interruptions, and final response states |
Check which events the adapter can see
Each adapter lists the events its framework reports and the events that are unavailable. Adapters do not guess by reading rendered text, timing interface changes, or using private framework fields.
Use the core integration directly when your app knows about retries, connection changes, or custom interactions that the framework adapter cannot see.
| Question | Use an adapter | Dispatch core events |
|---|---|---|
| Does the framework report the event you need? | Yes | Not required |
| Do you need the framework's IDs translated? | Yes | Optional |
| Does your app know when retries or connection changes happen? | Only if the framework reports them | Yes |
| Can the integration depend on rendered UI text? | Never | Never |
Install only the layers you use
Your app supplies a core runtime to its framework adapter. DOM or React handles browser announcements separately.
- Custom browser application: @generative-a11y/core and @generative-a11y/dom
- React application: @generative-a11y/core and @generative-a11y/react
- AI SDK: add @generative-a11y/ai-sdk to the core and delivery layers
- assistant-ui: add @generative-a11y/assistant-ui to the core and delivery layers
- AG-UI or CopilotKit v2: add @generative-a11y/ag-ui to the core and delivery layers