React SDK

The React SDK exports A11yProvider, useA11y(), and pre-built UI components. It wraps the vanilla SDK in a React context so all components in your tree can access the accessibility state without prop-drilling.

1. Wrap your app with A11yProvider

Place A11yProvider at the root of your application (or around the section that needs accessibility support). Pass your API key and the studentId of the currently logged-in user.

src/main.tsx

import { A11yProvider } from '@angstroma/a11y-sdk'

function App() {
  return (
    <A11yProvider
      apiKey="ang_live_YOUR_KEY"
      studentId={currentUser.id}      // your user's ID (string)
      locale="en"                     // optional: 'en' | 'es' | 'fr' | 'de' | 'pt' | 'ja' | 'ko' | 'zh' | 'ar' | 'hi' | 'si'
    >
      <YourApp />
    </A11yProvider>
  )
}

Note

When studentId is provided, A11yProvider automatically loads the student's accessibility profile on mount and applies their saved feature settings to the DOM. If studentId is omitted, features can still be toggled manually but no profile is persisted.

2. Use the useA11y() hook

Call useA11y() from any component inside the provider to access the full accessibility API.

src/components/AccessibilityControls.tsx

import { useA11y } from '@angstroma/a11y-sdk'

export function AccessibilityControls() {
  const {
    profile,          // UserProfile | null
    enabledFeatures,  // Set<string>
    isLoading,        // boolean
    error,            // string | null
    presets,          // Preset[]
    enable,           // (featureCode: string, value?: string | null) => void
    disable,          // (featureCode: string) => void
    toggle,           // (featureCode: string, value?: string | null) => void
    applyPreset,      // (presetCode: string) => Promise<void>
    resetAll,         // () => void
    save,             // () => Promise<void>
    reload,           // () => Promise<void>
  } = useA11y()

  return (
    <div>
      <button onClick={() => toggle('reading_mask')}>
        {enabledFeatures.has('reading_mask') ? 'Disable' : 'Enable'} Reading Mask
      </button>

      <button onClick={() => applyPreset('dyslexia-friendly')}>
        Apply Dyslexia Preset
      </button>

      <button onClick={() => save()}>
        Save preferences
      </button>
    </div>
  )
}

A11yConfig options

All options passed to A11yProvider:

Prop	Type	Default	Description
apiKey	string	â€”	Required. Your tenant API key.
studentId	string	undefined	External user ID to load/save a profile.
apiUrl	string	https://api.angstroma.com/api/v1	Override for custom or staging deployments.
tenant	string	undefined	Tenant slug. Resolved from API key if omitted.
locale	string	"en"	UI locale. Supported: en, es, fr, de, pt, ja, ko, zh, ar, hi, si.
autoLoadProfile	boolean	true	Load the student profile on mount.
trackUsage	boolean	true	Send feature activation events to analytics.
container	string \| HTMLElement	undefined	Scope CSS modifications to this element.
planFeatures	string[]	undefined	Feature codes unlocked by plan. Omit to allow all.

Pre-built components

Import ready-made components from the SDK:

import {
  A11yToolbar,       // Full accessibility toolbar (all features)
  A11yReader,        // Text-to-speech reader
  A11yQuizToolbar,   // Toolbar optimised for quiz/assessment pages
  A11yPresetBar,     // Horizontal preset picker
} from '@angstroma/a11y-sdk'

// Render inside A11yProvider:
<A11yToolbar />
<A11yPresetBar />

AI content transforms

Use AI functions directly in your components. These call the Angstroma API and count against your plan's AI call quota.

import { useA11y } from '@angstroma/a11y-sdk'

function QuestionCard({ question, answer }) {
  const { client } = useA11y()

  // Simplify reading level
  const simplified = await simplify(client, {
    text: question,
    targetGradeLevel: 5,
  })

  // Generate alt text for an image
  const alt = await generateAltText(client, {
    imageUrl: 'https://example.com/diagram.png',
    context: 'Biology cell diagram',
  })

  // Get hints without revealing the answer
  const hints = await getHints(client, {
    question,
    correctAnswer: answer,
    gradeLevel: 8,
    subject: 'science',
  })
}

Important

AI functions require a plan with AI credits. Calls that exceed the quota return a 429 error. Catch A11yApiError with status === 429 and show a graceful fallback.