AccessKit

Getting Started

Introduction

Understand how AccessKit's three layers fit together and when to use each one.

4 min read

Introduction

AccessKit is an end-to-end accessibility toolkit for React. It provides a single package for storing and applying user preferences and for finding and fixing issues, while giving end users control over how they experience your app. Everything in AccessKit is built around three layers that work together: a Provider that holds and applies settings, a Dev Tool for developers, and an Accessibility Widget for users. You can use the Provider alone, or add the Dev Tool, the Widget, or both.

1. AccessKitProvider - the foundation

AccessKitProvider is the core. You wrap your app with it once (for example in your root layout). It:

  • Stores user preferences: reduced motion, high contrast, enhanced focus, text spacing (letter, word, line), font size, dyslexia-friendly font, and color vision mode (protanopia, deuteranopia, tritanopia).
  • Applies those preferences by setting data-accesskit-* attributes and global styles on <html>, so your CSS can react via selectors like [data-accesskit-reduced-motion="true"] or [data-accesskit-high-contrast="true"].
  • Persists settings in localStorage by default so choices survive reloads and sessions.
  • Exposes a React context so any component under the provider can read or update settings via the useAccessKit hook.

When to use it: Always. The Provider is required. Without it, there is no shared state for preferences, and the Widget and Dev Tool have nowhere to read or write settings. Add it at the root of your app and keep it there.

2. AccessKitDevTools - for developers

AccessKitDevTools is a floating panel that runs accessibility audits on the live DOM . Its purpose is to help you catch issues before they ship. It:

  • Runs WCAG 2.0, 2.1, and 2.2 Level A, AA, and AAA rules by default, with optional rule sets (e.g. best-practice, Section 508, EN 301 549) via the additionalRules prop.
  • Lets you filter findings by severity (error / warning), WCAG level (A / AA / AAA), and category (color, forms, ARIA, keyboard, etc.).
  • Shows fix guidance and documentation links for each finding so you can resolve issues quickly.
  • Can be conditional (e.g. only in development or staging) so you can tree-shake it from production builds if you want.

When to use it: Use it whenever you’re building or auditing — in local development, in staging, or in CI. Add it inside AccessKitProvider and, if you like, guard it with something like process.env.NODE_ENV === "development" so it doesn’t ship to end users. You can also use the same audit engine programmatically via runAccessibilityAudit() for tests or custom tooling.

3. AccessibilityWidget - for end users

AccessibilityWidget is a floating control that lets visitors change how they experience your app. Place it once inside AccessKitProvider (e.g. in a layout or root component). It:

  • Renders a floating tab that opens a panel where users can toggle reduced motion, high contrast, focus indicators, text spacing, font size, dyslexia-friendly font, and color vision mode.
  • Applies changes immediately; the Provider writes them to the DOM and (by default) to localStorage.
  • Is themeable via the style prop (primary, panel background, text, borders, etc.) and positionable (e.g. center-right, bottom-left) so it fits your layout and brand.

When to use it: Use it when you want to give users control over motion, contrast, focus, spacing, font, and color vision. One widget per app is enough. It’s optional: if you only need to apply preferences programmatically (e.g. from your own settings screen), the Provider and useAccessKit are enough.

How they fit together

  • AccessKitProvider is always the base: it owns the settings and applies them to the page.
  • AccessKitDevTools and AccessibilityWidget both live inside the provider. The Dev Tool uses the same DOM the provider is affecting so audits reflect the current state; the Widget updates the same settings the provider stores and applies.
  • You can use Provider + Widget (user-facing preferences, no dev UI), Provider + DevTools (developer-only auditing), or Provider + Widget + DevTools (full setup: users get the widget, developers get the panel in dev).

From here, you can go to Installation and Quick Start to add the package and wire up the Provider, then add the Dev Tool and Widget as needed.

Back to documentation