Development: Node.js 22.13 or newer, npm, Git. Library peers: React/React DOM 18.3.1 or 19.x. Keep React and React DOM on the same version. There are no application environment variables, API keys, backend services or mandatory network access at runtime. Storage is optional (persist={false}).
The package identity is accessibility-plugin-react. Version 2 is the current
major line and latest is the stable distribution tag. The API changes from
the historical 1.x package require migration (see MIGRATION.md). Install the
current release with npm install accessibility-plugin-react, or pin the
major line with npm install accessibility-plugin-react@2. For this checkout:
npm ci
npm run build
npm pack
# From an independent application:
npm install /absolute/path/to/accessibility-plugin-react-2.0.1.tgzImporting accessibility-plugin-react automatically injects its scoped CSS in browser environments. The standalone accessibility-plugin-react/style.css export remains available for explicit stylesheet pipelines. Do not add the library to a Tailwind content scan. No shadcn, icon or Motion dependency is needed. See README for complete React/Vite JSX.
Keep custom hooks and custom apply callbacks in a Client Component. The built library preserves its own client boundary. The root layout may remain a Server Component.
// app/preferences.tsx
"use client";
import {
AccessibilityPlugin,
AccessibilityButton,
AccessibilityList,
FontSizeController,
GrayscaleController,
ResetController,
} from "accessibility-plugin-react";
export default function Preferences() {
return (
<AccessibilityPlugin>
<AccessibilityButton />
<AccessibilityList>
<FontSizeController />
<GrayscaleController />
<ResetController />
</AccessibilityList>
</AccessibilityPlugin>
);
}// app/layout.tsx
import type { ReactNode } from "react";
import Preferences from "./preferences";
export default function RootLayout({ children }: { children: ReactNode }) {
return (
<html lang="en">
<body>
{children}
<Preferences />
</body>
</html>
);
}Mount the widget in the persistent root layout, not each route. Do not place document reads inside render. Do not disable SSR merely to mask hydration problems. Effects and portals appear on the client after hydration; a brief default-style paint can occur.
A complete runnable example is available in examples/next-app/.
For strict Content Security Policy environments (such as disabling inline styles or generating cryptographic nonces), see the dedicated Content Security Policy Guidance for full Next.js and Vite recipes.
// pages/_app.tsx
import type { AppProps } from "next/app";
import Preferences from "../components/preferences"; // same component as above
export default function App({ Component, pageProps }: AppProps) {
return (
<>
<Component {...pageProps} />
<Preferences />
</>
);
}Load library CSS after a host reset and load intentional widget overrides afterward. There is no library global preflight. Portals are independent of application layout and filter effects. Global host styles can still affect inherited properties or override selectors, especially with !important; inspect computed styles if controls differ.
Filters create a containing block for fixed host descendants. Test sticky/fixed headers, modals, menus, images and third-party overlays in your real application. Text measurement does not enter iframe documents or Shadow DOM. Hiding videos is visual only and is not a playback-control feature. See CSP guidance and troubleshooting for CSP and font-loading considerations.
Automated scripts install the packed archive into separate directories rather than importing repository source. They exercise ESM, CommonJS, declarations, SSR, production Vite builds, and production Next App/Pages routes. Exact framework/browser versions and actual results are in PROJECT_STATUS.md. Broader versions allowed by peer ranges are compatibility targets, not individually verified claims.