NGP Accessibility

React accessibility package with translation, text sizing, contrast modes, and more.

Features

• 🌐 Multi-language support (English, Tagalog, Cebuano/Visayan)
• 🌐 Google auto-translation for page content with manual UI fallback
• 📏 Text size adjustment (increase/decrease)
• 🎨 High contrast mode
• 🔄 Negative contrast mode
• 💡 Light background mode
• 🔗 Links underline toggle
• 📖 Readable font mode
• ✅ TypeScript & JavaScript compatible
• 📦 Zero dependencies (peer: React)

Installation

npm install ngp-accessibility

Usage

Option 1: Toolbar (Horizontal)

import { AccessibilityProvider, AccessibilityToolbar } from "ngp-accessibility";
import "ngp-accessibility/dist/styles.css";

function App() {
  return (
    <AccessibilityProvider googleTranslateTargetSelector="main">
      <AccessibilityToolbar />
      <main>
        <YourContent />
      </main>
    </AccessibilityProvider>
  );
}

Option 2: Dropdown Button

import {
  AccessibilityProvider,
  AccessibilityDropdown,
} from "ngp-accessibility";
import "ngp-accessibility/dist/styles.css";

function App() {
  return (
    <AccessibilityProvider googleTranslateTargetSelector="#page-content">
      <div style={{ textAlign: "right", padding: "10px" }}>
        <AccessibilityDropdown />
      </div>
      <section id="page-content">
        <YourContent />
      </section>
    </AccessibilityProvider>
  );
}

API

AccessibilityProvider

Wrap your app with this provider.

Props:

• translations: Manual translations for your own keyed content through t().
• googleTranslateTargetSelector: CSS selector for the DOM subtree that should be eligible for Google auto-translation. Defaults to main.

Example:

<AccessibilityProvider googleTranslateTargetSelector="#article-content">
  <Header />
  <AccessibilityDropdown />
  <div id="article-content">
    <ArticlePage />
  </div>
</AccessibilityProvider>

Only the subtree matched by googleTranslateTargetSelector should contain the content you want Google to translate. Elements outside that path are marked as notranslate.

Language Behavior

setLanguage(lang) updates the current language state once, and the package applies that language in 3 different ways:

1. Toolbar and dropdown UI labels use translate(key).
2. Your app's keyed content uses t(key).
3. Google Translate auto-translates the subtree matched by googleTranslateTargetSelector.

This means the package now supports 2 language modes:

• Manual UI language: If the selected language exists in the built-in package dictionary, the accessibility controls use those manual labels.
• Google-only language: If the selected language does not have a built-in package dictionary, the accessibility controls fall back to English while Google still translates the page content.

Example:

• tl: package UI uses manual Tagalog labels, and page content can also be translated.
• ja: package UI falls back to English unless you add manual Japanese labels, while Google translates the selected page subtree to Japanese.

Manual Translation For Specific Content

Yes, this setup is more flexible when you want manual translations only for specific components or content.

Use translations plus t(key) when you want full control over exact wording in your own app content. Use Google Translate for the rest of the page content inside your translation target.

Example:

const myTranslations = {
  en: {
    heroTitle: "Welcome",
    heroBody: "This section is manually translated.",
  },
  ja: {
    heroTitle: "ようこそ",
    heroBody: "このセクションは手動で翻訳されています。",
  },
};

function Hero() {
  const { t } = useAccessibility();

  return (
    <section>
      <h1>{t("heroTitle")}</h1>
      <p>{t("heroBody")}</p>
    </section>
  );
}

function App() {
  return (
    <AccessibilityProvider
      translations={myTranslations}
      googleTranslateTargetSelector="main"
    >
      <AccessibilityDropdown />
      <main>
        <Hero />
        <OtherPageContent />
      </main>
    </AccessibilityProvider>
  );
}

In that setup:

• Hero can use your manual translations through t(key).
• other content inside main can still be translated by Google.
• the accessibility toolbar/dropdown uses built-in package labels when available, otherwise English fallback.

useAccessibility()

Hook that returns:

• language, setLanguage(lang)
• hasManualTranslations
• textSize, increaseText(), decreaseText()
• highContrast, toggleHighContrast()
• negativeContrast, toggleNegativeContrast()
• lightBackground, toggleLightBackground()
• underlineLinks, toggleUnderlineLinks()
• readableFont, toggleReadableFont()
• translate(key) - Get translated package UI text with English fallback
• t(key) - Get your app-specific manual text for the current language, then fall back to English, then the raw key

AccessibilityToolbar

Pre-built toolbar component with all controls.

Redesign And Theming

You can fully redesign the package UI in 3 ways:

1. Override CSS variables (fastest)

:root {
  --ngp-a11y-bg: #101418;
  --ngp-a11y-surface: #1b232c;
  --ngp-a11y-surface-hover: #243241;
  --ngp-a11y-text: #f2f6fa;
  --ngp-a11y-border: #2d3a48;
  --ngp-a11y-accent: #16a34a;
  --ngp-a11y-accent-hover: #15803d;
  --ngp-a11y-accent-text: #ffffff;
  --ngp-a11y-radius: 999px;
}

2. Pass custom classes to sub-elements

<AccessibilityToolbar
  className="my-toolbar"
  classes={{
    button: "my-btn",
    activeButton: "my-btn-active",
    select: "my-select",
  }}
/>

<AccessibilityDropdown
  classes={{
    toggle: "my-toggle",
    menu: "my-menu",
    section: "my-section",
    button: "my-btn",
    activeButton: "my-btn-active",
  }}
/>

3. Replace the dropdown trigger UI entirely

<AccessibilityDropdown
  renderTrigger={({ isOpen, toggle, className }) => (
    <button className={`${className} custom-trigger`} onClick={toggle}>
      {isOpen ? "Close Tools" : "Open Accessibility"}
    </button>
  )}
/>

TypeScript users can import the prop types directly:

• AccessibilityToolbarProps
• AccessibilityToolbarClasses
• AccessibilityDropdownProps
• AccessibilityDropdownClasses

Full Documentation

For complete documentation including:

• Full page translation guide
• Custom toolbar examples
• TypeScript support
• CSS customization
• Advanced usage examples

See DOCUMENTATION.md

License

MIT