Docs · JavaScript SDK

JavaScript SDK

The @incluxa/a11y-sdk npm package (coming soon) will give you programmatic control over every accessibility feature — profiles, presets, AI transforms, and usage analytics — from any JavaScript environment.

npm package coming soon — use the script tag today. @incluxa/a11y-sdk is not published to npm yet, so the install commands and imports on this page show the planned API and will not work until it is released. To add the widget today, paste the script tag before </body>:

index.html

<script
  src="https://cdn.incluxa.com/widget.js"
  data-key="inc_live_YOUR_KEY"
  async
></script>

When to use the SDK vs script tag

The script tag is the fastest path to adding the INCLUXA accessibility toolbar to any site. No build step required.

The npm SDK is for teams who need deeper integration: building custom UI, programmatically applying presets per student, using AI content transforms in your own components, or building headless (no toolbar) implementations.

Script tag

Drop-in toolbar widget. No build step. Best for static sites, CMS platforms, and quick installs. See the Quickstart.

React SDK

A11yProvider + useA11y() hook. Context-driven, React 18+ compatible.

Vanilla JS SDK

IncluxaA11y class. Works in any framework or plain HTML. No React dependency.

Installation (coming soon)

Once the package is published, install it from npm:

npm install @incluxa/a11y-sdk

What's included

Export	Description
A11yProvider	React context provider — wraps your app, loads profile automatically
useA11y()	React hook — access enable/disable/toggle/applyPreset from any component
A11yToolbar	Pre-built React toolbar component
A11yReader	Text-to-speech reader component
A11yQuizToolbar	Accessibility toolbar optimised for quiz/assessment UIs
A11yPresetBar	Horizontal preset picker component
IncluxaA11y	Vanilla JS class — full SDK without React dependency
A11yClient	Low-level HTTP client (X-Api-Key auth)
generateAltText()	AI: generate alt text from image URL
simplify()	AI: simplify text to target reading level
rephrase()	AI: rephrase question/answer pair
getHints()	AI: get scaffolded hints for a question
extractVocabulary()	AI: extract vocabulary words from text

API base URL

All SDK methods send requests to https://api.incluxa.com/api/v1 by default. Override with the apiUrl config option for self-hosted or staging environments.

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 '@incluxa/a11y-sdk'

function App() {
  return (
    <A11yProvider
      apiKey="inc_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>
  )
}

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 '@incluxa/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.incluxa.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 '@incluxa/a11y-sdk'

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

AI content transforms

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

import { useA11y } from '@incluxa/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',
  })
}

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.

Vanilla JS SDK

IncluxaA11y is a framework-agnostic class that gives you full control over accessibility features, profiles, and AI transforms — no React dependency required. Works with Vue, Angular, Svelte, plain HTML, or any server-rendered application.

Basic setup

main.js

import { IncluxaA11y } from '@incluxa/a11y-sdk'

const a11y = new IncluxaA11y({
  apiKey: 'inc_live_YOUR_KEY',
  studentId: currentUser.id,   // optional: loads/saves the user's profile
})

// Mount on an element (or omit to scope to document.body)
await a11y.mount('#content')

// Profile is loaded automatically — DOM is updated
console.log(a11y.getEnabledFeatures())  // ['reading_mask', 'large_cursor', ...]

Feature control

// Enable a feature
a11y.enable('reading_mask')
a11y.enable('text_zoom', '150')   // with an optional value

// Disable a feature
a11y.disable('reading_mask')

// Toggle on/off
a11y.toggle('large_cursor')

// Check state
a11y.isEnabled('large_cursor')   // boolean

// Get all enabled codes
a11y.getEnabledFeatures()        // string[]

// Reset all features to off
a11y.reset()

Presets

// Apply a named preset
await a11y.applyPreset('dyslexia-friendly')

// List available presets
const presets = await a11y.getPresets()
// [{ code: 'dyslexia-friendly', name: 'Dyslexia Friendly', ... }, ...]

Saving preferences

Call save() to persist the current feature state to the user's profile in the INCLUXA API. On next mount(), those settings are restored automatically.

// Save current state to the API
await a11y.save()

// Reload profile from the API
await a11y.loadProfile()

AI transforms

// Simplify text to a reading level
const result = await a11y.simplify(
  'The mitochondria is the powerhouse of the cell.',
  5   // target grade level
)
console.log(result.result)   // simplified text

// Generate alt text for an image
const alt = await a11y.generateAltText(
  'https://example.com/diagram.png',
  'Biology diagram'    // optional context hint
)

// Get scaffolded hints for a question
const hints = await a11y.getHints(
  'What is photosynthesis?',
  'Plants use sunlight to make food',
  { gradeLevel: 6, subject: 'biology' }
)

// Extract vocabulary words
const vocab = await a11y.extractVocabulary(
  'The cytoplasm surrounds the nucleus...',
  6   // grade level
)

// Rephrase a question/answer pair
const rephrased = await a11y.rephrase(
  'What is the boiling point of water?',
  '100°C at standard pressure',
  8   // grade level
)

Feature sub-modules

For direct DOM manipulation without the full class, import individual feature modules:

import { IncluxaA11y } from '@incluxa/a11y-sdk'

const a11y = new IncluxaA11y({ apiKey: '...' })

// Direct sub-module access
a11y.tts.speak('Hello, world')
a11y.tts.stop()

a11y.readingMask.enable()
a11y.readingMask.disable()

a11y.bionicReading.enable(document.getElementById('content'))

a11y.contrast.enable('high')   // 'high' | 'inverted' | 'monochrome'

a11y.textZoom.set(150)         // percentage

a11y.largeCursor.enable()
a11y.focusHighlight.enable()
a11y.reducedMotion.enable()

Cleanup

// Remove all accessibility effects and clean up event listeners
a11y.destroy()

Call a11y.destroy() in your framework's component unmount hook to prevent memory leaks and stale DOM mutations.

Error handling

import { IncluxaA11y, A11yApiError } from '@incluxa/a11y-sdk'

try {
  await a11y.applyPreset('dyslexia-friendly')
} catch (err) {
  if (err instanceof A11yApiError) {
    if (err.status === 429) {
      console.warn('AI quota exceeded')
    } else if (err.status === 401) {
      console.error('Invalid API key')
    } else {
      console.error(`API error ${err.status}: ${err.body}`)
    }
  }
}

Add INCLUXA to your app

Grab an API key, add the script tag today (the @incluxa/a11y-sdk npm package is coming soon), and start with the REST API reference.

Get an API key REST API reference