react-native-a11y-suite

A comprehensive, production-grade accessibility toolkit and testing platform for React Native.
Built from the ground up for the New Architecture (TurboModules & Fabric) with full WCAG 2.2 conformance.

Explore Features • Quick Start • Interactive Example • Documentation • WCAG 2.2 Guide

✨ Features

• 🔍 Reactive System State Detection — Real-time reactive listeners for TalkBack, VoiceOver, Switch Access, Voice Control, font scale factor, reduced motion, high contrast, and inverted colors.
• 📢 Screen Reader Service — Post assertive/polite announcements, manage accessibility focus, and restore focus histories across modal dialogs and screen navigation (WCAG 2.4.2, 2.4.3).
• ⚛️ Idiomatic React Hooks — useScreenReaderStatus, useReducedMotion, useFontScale, useAccessibilityState, useA11yAnnounce, and useA11yTranslation.
• 🧩 Accessible UI Components — AccessibleTouchTarget (WCAG 2.5.5/2.5.8), AccessibleHeading (WCAG 1.3.1/2.4.6), and LiveRegion (WCAG 4.1.3).
• 🧠 Cognitive Accessibility — Session timeout extensions with warning lead times (WCAG 2.2.1), Flesch-Kincaid reading grade calculation (WCAG 3.1.5), and redundant entry prevention caching (WCAG 3.3.7).
• 🖐️ Motor & Physical Accessibility — Switch Access & Voice Control detection, minimum touch target enforcement, and drag-and-drop pointer alternatives (WCAG 2.5.1, 2.5.7).
• 👂 Hearing Accessibility — Subtitles & Closed Captions preference awareness (WCAG 1.2.2) and visual substitute alerts for auditory cues (WCAG 1.4.2).
• 📝 Form Accessibility Helper — Standardized error announcements, required field markers, and input purpose mappings (WCAG 1.3.5, 3.3.1, 3.3.2).
• 🧭 Navigation & Focus Management — Modal focus trapping/restoration stack and screen transition announcements (WCAG 2.4.1, 2.4.2, 2.4.3).
• 🎯 Full WCAG 2.2 Registry — Complete 87 success criteria categorized into Automated, Partially Automated, and Manual rules with native platform mappings.
• 🧪 Automated Jest Matchers — expect(element).toHaveValidA11yLabel() and expect(element).toHaveMinimumTouchTarget() for continuous integration test suites.
• 🌐 Internationalization (i18n) — Built-in react-i18next integration with English (en) defaults and full custom translation override support.
• ⚡ New Architecture Native TurboModule — Native Swift (iOS) and Kotlin (Android) modules with automatic fallback for legacy bridge and Jest environments.

📦 Installation

npm install react-native-a11y-suite
# or
yarn add react-native-a11y-suite

Peer Dependencies

Ensure you have react (>=18.0.0) and react-native (>=0.76.0) installed in your project:

npm install [email protected] [email protected] [email protected] [email protected]

iOS CocoaPods Setup

cd ios && pod install

🚀 Quick Start

1. Initialize the Suite

Initialize A11ySuite in your root entry point (index.js or App.tsx):

import A11ySuite from 'react-native-a11y-suite';

// Initialize core listeners and native state detection
A11ySuite.initialize();

2. Using Reactive Accessibility Hooks

import React from 'react';
import {View, Text, TouchableOpacity, StyleSheet} from 'react-native';
import {
  useScreenReaderStatus,
  useReducedMotion,
  useFontScale,
  useA11yAnnounce,
} from 'react-native-a11y-suite';

export function AccessibilityDashboard() {
  const isScreenReaderActive = useScreenReaderStatus();
  const isReducedMotion = useReducedMotion();
  const fontScale = useFontScale();
  const {announce} = useA11yAnnounce();

  return (
    <View style={styles.container}>
      <Text style={styles.text}>
        Screen Reader: {isScreenReaderActive ? '🟢 Active' : '⚪ Inactive'}
      </Text>
      <Text style={styles.text}>
        Reduced Motion: {isReducedMotion ? '🟢 Enabled' : '⚪ Disabled'}
      </Text>
      <Text style={styles.text}>Font Scale: {fontScale}x</Text>

      <TouchableOpacity
        style={styles.button}
        onPress={() => announce('Order placed successfully!')}
        accessibilityRole="button"
        accessibilityLabel="Place Order">
        <Text style={styles.buttonText}>Place Order</Text>
      </TouchableOpacity>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {padding: 20},
  text: {fontSize: 16, marginBottom: 8},
  button: {backgroundColor: '#007AFF', padding: 12, borderRadius: 8},
  buttonText: {color: '#FFF', textAlign: 'center', fontWeight: 'bold'},
});

3. Accessible UI Primitives

AccessibleTouchTarget (WCAG 2.5.5 / 2.5.8)

Ensures touch targets satisfy minimum requirements (44pt on iOS, 48dp on Android) without distorting the visual layout:

import React from 'react';
import {TouchableOpacity, Text} from 'react-native';
import {AccessibleTouchTarget} from 'react-native-a11y-suite';

export function SmallIconButton({onPress}) {
  return (
    <AccessibleTouchTarget minSize={48}>
      <TouchableOpacity
        onPress={onPress}
        accessibilityLabel="Bookmark this article"
        accessibilityRole="button">
        <Text>★</Text>
      </TouchableOpacity>
    </AccessibleTouchTarget>
  );
}

AccessibleHeading (WCAG 1.3.1 / 2.4.6)

Renders semantic heading levels for screen reader rotor navigation:

import { AccessibleHeading } from 'react-native-a11y-suite';

<AccessibleHeading level={1}>Account Settings</AccessibleHeading>
<AccessibleHeading level={2}>Privacy & Security</AccessibleHeading>

LiveRegion (WCAG 4.1.3)

Notifies assistive technologies dynamically when content changes:

import {LiveRegion} from 'react-native-a11y-suite';

<LiveRegion mode="polite">
  <Text>{uploadStatusMessage}</Text>
</LiveRegion>;

4. Form Accessibility Helper (WCAG 3.3.1 / 3.3.2)

Standardize form accessibility labels, required attributes, hints, and error states:

import React, {useState} from 'react';
import {TextInput, Text, View} from 'react-native';
import {FormAccessibilityHelper} from 'react-native-a11y-suite';

export function EmailInputField() {
  const [email, setEmail] = useState('');
  const [error, setError] = useState('');

  const fieldProps = FormAccessibilityHelper.getFieldProps({
    label: 'Email Address',
    hint: 'Enter your account login email',
    required: true,
    errorMessage: error,
    isValid: error === '',
  });

  return (
    <View>
      <TextInput
        {...fieldProps}
        value={email}
        onChangeText={setEmail}
        keyboardType="email-address"
      />
      {error ? <Text accessibilityRole="alert">{error}</Text> : null}
    </View>
  );
}

5. Automated CI Testing with Jest Matchers

Add automated accessibility checks to your Jest test suites:

import React from 'react';
import { render } from '@testing-library/react-native';
import { registerA11yMatchers } from 'react-native-a11y-suite';

// Register custom matchers once
registerA11yMatchers();

test('submit button complies with accessibility standards', () => {
  const { getByTestId } = render(<SubmitButton testID="submit-btn" />);
  const button = getByTestId('submit-btn');

  // Verify non-empty accessibility label
  expect(button).toHaveValidA11yLabel();

  // Verify minimum 44x44 touch target dimensions
  expect(button).toHaveMinimumTouchTarget(44);
});

📱 Example App

A full React Native New Architecture demo app is available in the example/ folder.

To run the example app:

cd example
npm install
npm run start

For iOS:

npm run ios

For Android:

npm run android

🏗️ Architecture

react-native-a11y-suite/
├── src/
│   ├── core/           # A11ySuite singleton & NativeModuleProxy
│   ├── specs/          # TurboModule Codegen spec (NativeA11ySuite)
│   ├── hooks/          # React hooks (useAccessibilityState, useFontScale, etc.)
│   ├── components/     # Accessible UI Primitives (AccessibleTouchTarget, LiveRegion, etc.)
│   ├── cognitive/      # Cognitive services (readability, timeouts, redundant entry)
│   ├── motor/          # Motor services (switch access, target sizing, drag alternatives)
│   ├── hearing/        # Hearing services (captions status, visual audio cues)
│   ├── forms/          # Form accessibility helper (error & required labels)
│   ├── navigation/     # FocusManager (modal focus restore, screen announcements)
│   ├── i18n/           # react-i18next translation system (English)
│   ├── wcag/           # 87 WCAG 2.2 criteria registry
│   ├── audit/          # RuleEngine & ScoringEngine
│   ├── utils/          # Common math, color contrast, and safe execution helpers
│   ├── types/          # Centralized interfaces and types
│   └── testing/        # Custom Jest matchers
├── android/            # Kotlin TurboModule implementation
├── ios/                # Swift TurboModule implementation
└── example/            # Full interactive New Architecture demo app

📚 In-Depth Documentation

• 🚀 Getting Started Guide — Architecture, installation, and TurboModules.
• ⚛️ React Hooks Guide — Detailed hook APIs and usage examples.
• 🧩 Accessible Components — UI primitives and accessibility guidelines.
• 🎯 WCAG 2.2 Guide — 87 success criteria, POUR principles, and native platform coverage.
• 🧪 Testing & CI Guide — Jest matchers, assertions, and GitHub Actions setup.
• 🧠 Domain Services — Cognitive, Motor, Hearing, Form, and Navigation services.
• 🌐 Internationalization — i18n dictionary and dynamic translation hooks.

🔒 Privacy & Compliance

• Zero Telemetry: Does not track, collect, or transmit any user data.
• Zero Fingerprinting: Native accessibility states are accessed strictly via standard OS APIs for real-time assistive rendering.
• 100% WCAG 2.2 Conformance: Complete mapping and rule analysis for Levels A, AA, and AAA.

📄 License

MIT © Vengateswaran