React hooks

Bind an existing chat interface

AttentionRefs contain refs only. Add them to semantic elements already in your app.

import {
  useAttention,
  useAttentionRefs,
  usePreferences,
  useRuntime,
} from "@generative-a11y/react";

function ExistingChat() {
  const runtime = useRuntime();
  const attention = useAttention();
  const { setPreferences } = usePreferences();
  const bindings = useAttentionRefs();

  return (
    <main ref={bindings.conversationRef}>
      <article ref={bindings.newestResponseRef}>Latest response</article>
      <textarea aria-label="Message" ref={bindings.composerRef} />
      <button onClick={() => runtime.dispatch({ type: "response.started", responseId: "answer" })}>Send</button>
      <output>{attention.mode}</output>
      <button onClick={() => setPreferences({ version: 1, preset: "balanced", streaming: "completion", tools: "preset" })}>
        Save completion preference
      </button>
    </main>
  );
}

Mount these hooks under A11yProvider. Refs observe existing elements without changing their markup or styles; preference updates are validated before the store publishes them. Saving preferences does not change the active runtime policy. Apply them when constructing the next runtime or remounting its provider at an intentional session boundary.

Hook results

AttentionRefs

Each property is a callback ref for an existing host element. These optional refs observe attention only; they do not add semantics or enable announcement delivery. Compose existing refs with your framework utility when necessary.

useAttentionControl

Returns { state: { observed, override, effective }, setOverride }. Call setOverride("quiet"), setOverride("normal"), or setOverride("auto") from controls owned by your host app. The provider adds no visible controls. With attention filtering disabled, effective mode remains normal.

Set the provider's attentionPolicy prop to bridge browser observations and independently configure core policy.attention.enabled. Copy a complete provider and ref-binding example.