@generative-a11y/react

A11yProvider

A11yProvider can own a runtime or borrow one from your app. It renders stable hidden delivery regions and leaves visible UI unchanged.

components/app.tsx

import { A11yProvider } from "@generative-a11y/react";

export function App() {
  return (
    <A11yProvider>
      <ExistingChat />
    </A11yProvider>
  );
}

Wrap the part of your app that sends events. The provider supplies browser delivery by default; your existing components retain their markup, keyboard behavior, and focus. See React hooks to read the runtime.

Provider options

The provider also accepts RuntimeOptions when it creates a runtime, including preset, policy, messages, and clock.

Prop

Type

Provider ownership

A11yProvider cleans up every runtime, browser connection, store, timer, subscription, and live region it creates. Anything supplied by your app remains under your control.

Provider context is unavailable outside the provider.
Server rendering uses stable hidden structure and reports attention as unknown.
Routine announcements never move focus.
Initial preferences configure an owned runtime only when no explicit preset or policy is supplied. Later preference changes update the store, not the active runtime policy.

Opt-in attention forwarding

A11yProvider accepts attentionPolicy?: boolean (default false). This forwards browser observations to the runtime; independently enable policy.attention.enabled for filtering. useAttentionControl exposes observed, override, and effective state plus setOverride. See the complete attention guide.

Localized announcements

See catalogs and adapter copy for the typed messages and copy options, language ownership, validation, construction lifetime, and replay requirements. Existing lifecycle evidence and timing remain unchanged.

Public declarations: @generative-a11y/react

All exported values and types for this entry point. Import these names from @generative-a11y/react; the signatures below are reference material, not a replacement for the ownership and lifecycle guidance above.

A11yContextValue — type

interface A11yContextValue {
    readonly runtime: Runtime;
    readonly attentionStore: AttentionStore;
    readonly preferenceStore: PreferenceStore;
}

A11yProvider — value

declare function A11yProvider({ children, runtime: suppliedRuntime, delivery, attention, attentionStore: suppliedAttentionStore, attentionPolicy, preferences, preferenceStore: suppliedPreferenceStore, ...runtimeOptions }: A11yProviderProps): react.JSX.Element;

A11yProviderProps — type

interface A11yProviderProps extends RuntimeOptions {
    readonly children?: ReactNode;
    readonly runtime?: Runtime;
    readonly delivery?: false | DeliveryOptions;
    readonly attention?: false | AttentionStoreOptions;
    readonly attentionStore?: AttentionStore;
    /** Opt into forwarding observations; configure runtime policy.attention separately. */
    readonly attentionPolicy?: boolean;
    readonly preferences?: PreferenceStoreOptions;
    readonly preferenceStore?: PreferenceStore;
}

AttentionControl — type

interface AttentionControl {
    readonly state: AttentionState;
    readonly setOverride: (mode: AttentionOverride) => void;
}

AttentionRefs — type

/** Optional refs that register host elements for attention observations only. */
interface AttentionRefs {
    readonly composerRef: RefCallback<HTMLElement>;
    readonly conversationRef: RefCallback<HTMLElement>;
    readonly newestResponseRef: RefCallback<HTMLElement>;
}

DeliveryOptions — type

type DeliveryOptions = Omit<AnnouncerOptions, "document" | "regions">;

PreferencesResult — type

interface PreferencesResult {
    readonly preferences: PreferenceSchemaV1;
    readonly setPreferences: (preferences: PreferenceSchemaV1) => void;
    readonly store: PreferenceStore;
}

useA11y — value

declare function useA11y(): A11yContextValue;

useAttention — value

declare function useAttention(): AttentionSnapshot;

useAttentionControl — value

declare function useAttentionControl(): AttentionControl;

useAttentionRefs — value

declare function useAttentionRefs(): AttentionRefs;

usePreferences — value

declare function usePreferences(): PreferencesResult;

useRuntime — value

declare function useRuntime(): Runtime;