AccessKit

Core Concepts

AccessKitProvider

Root context provider for accessibility settings. Wrap your app so the widget, dev tools, and useAccessKit work.

5 min read

AccessKitProvider is the root of AccessKit. It holds accessibility settings (reduced motion, contrast, font size, and so on), applies them to the document via data attributes and CSS variables, and can persist them in localStorage. Any component that uses the Accessibility Widget, Dev Tools, or the useAccessKit hook must be rendered inside AccessKitProvider.

Where to place it

Place AccessKitProvider as high as possible in your tree—usually in the root layout (e.g. app/layout.tsx in Next.js or your main App component). Wrap the entire app so every page and route has access to the same context and persisted settings.

tsx
// app/layout.tsx (Next.js App Router)
import { AccessKitProvider } from "@accesskit/react"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AccessKitProvider>
          {children}
        </AccessKitProvider>
      </body>
    </html>
  )
}

All props are optional.

  • defaultSettings – Partial object of initial settings (e.g. { highContrast: true, fontSize: 100 }). Omitted keys use built‑in defaults. Only needed if you want different defaults than the package.
  • storageKey – String key used for localStorage. Default is "accesskit:settings". Change it if you need to avoid clashes with another app on the same origin or support multiple “profiles.”
  • persist – If true (default), settings are saved to localStorage and restored on load. Set to false to keep settings in memory only (e.g. no persistence, or you persist elsewhere).
  • onPersistError - Optional callback (error: unknown) => void invoked when writing settings to localStorage fails (e.g. quota exceeded, private browsing, or storage disabled). Use this to show a toast, log to an error service, or inform the user that preferences won’t persist. If omitted, failures are silent in production (a console warning is logged in development).
  • focusColor – CSS color for the focus ring injected by the provider (e.g. "#0066cc" or "var(--primary)"). Use this to match your design system.

The type of defaultSettings is Partial<AccessKitSettings>. You can override any subset of the settings; the rest stay at their defaults.

What the provider does

AccessKitProvider does four things: it holds the current settings in React state, applies them to the page, optionally persists them, and exposes them (and updaters) through context.

  • State – Stores the current AccessKitSettings and merges any defaultSettings you pass with the built‑in defaults.
  • DOM and CSS – Writes data attributes on <html> (e.g. data-accesskit-reduced-motion, data-accesskit-high-contrast, data-accesskit-font-size) and sets CSS custom properties (e.g. --accesskit-font-size, --accesskit-letter-spacing). Your CSS can target these to implement reduced motion, high contrast, typography, and focus styles.
  • Persistence – When persist is true, the current settings object is saved to localStorage under storageKey on every change and read on first load so preferences survive refresh and return visits. If a write fails (e.g. quota exceeded or private browsing), the provider stops retrying for the current session, logs a warning in development, and calls onPersistError if provided. Settings continue to work in memory for the rest of the session; only cross-session persistence is affected.
  • Context – Provides the same object that useAccessKit() returns: settings plus setSetting, toggleSetting, setFontSize, setLetterSpacing, setWordSpacing, setLineHeight, and resetSettings. The Accessibility Widget and your own UI use this to read and update settings.

When the user turns on “Dyslexia-friendly font,” the provider injects the Lexend font (embedded or via a link). When a color-vision mode is chosen, it injects SVG filters for simulation (protanopia, deuteranopia, tritanopia) and applies them via the document’s filter style.

Settings shape (AccessKitSettings)

The settings object has these keys. You can pass a partial object as defaultSettings; the rest are filled with defaults.

  • reducedMotion (boolean) – When true, your CSS can respect data-accesskit-reduced-motion="true" to reduce or disable motion.
  • highContrast (boolean) – When true, a contrast filter is applied and data-accesskit-high-contrast="true" is set for your styles.
  • enhancedFocus (boolean) – When true, data-accesskit-enhanced-focus="true" is set so you can show stronger focus indicators.
  • letterSpacing (number, 0–100) – Letter spacing; 100 corresponds to 0.24em (WCAG‑style).
  • wordSpacing (number, 0–100) – Word spacing; 100 corresponds to 0.16em.
  • lineHeight (number, 0–100) – Line height scale; 0 ≈ 1.2, 100 ≈ 2.0.
  • fontSize (number, 80–200) – Base font size as a percentage (100 = 100%); applied via --accesskit-font-size.
  • dyslexiaFont (boolean) – When true, Lexend is injected and used for body text where you choose.
  • colorVision ("none" | "protanopia" | "deuteranopia" | "tritanopia") – Color vision simulation; "none" means no filter.

Using settings in your app

Use the useAccessKit hook inside the provider to read and update settings. That’s the same context the Accessibility Widget uses. For example, you can sync a custom control with the provider or reset to defaults.

tsx
import { useAccessKit } from "@accesskit/react"

function MySettingsPanel() {
  const { settings, setSetting, resetSettings } = useAccessKit()

  return (
    <div>
      <label>
        <input
          type="checkbox"
          checked={settings.reducedMotion}
          onChange={(e) => setSetting("reducedMotion", e.target.checked)}
        />
        Reduce motion
      </label>
      <button type="button" onClick={resetSettings}>
        Reset to defaults
      </button>
    </div>
  )
}

setSetting takes a setting key and a value (boolean, number, or string depending on the key). toggleSetting(key) flips boolean settings. resetSettings() restores the initial values (from defaultSettings plus defaults). For more details, see the TypeScript and Widget docs.

Data attributes and CSS variables

The provider sets attributes on <html> and CSS custom properties so your styles can react to user preferences. Use these in selectors or with var().

  • data-accesskit-reduced-motion – "true" or "false"
  • data-accesskit-high-contrast – "true" or "false"
  • data-accesskit-enhanced-focus – "true" or "false"
  • data-accesskit-dyslexia-font – "true" or "false"
  • data-accesskit-color-vision – "none", "protanopia", "deuteranopia", or "tritanopia"
  • data-accesskit-font-size – Current font size percentage (e.g. "100")
  • data-accesskit-letter-spacing – Set when letter spacing > 0 (e.g. "50")
  • data-accesskit-word-spacing – Set when word spacing > 0
  • data-accesskit-line-height – Set when line height > 0

Relevant CSS variables include --accesskit-font-size (e.g. 100%), --accesskit-letter-spacing, --accesskit-word-spacing, and --accesskit-line-height. The provider also injects a small style block for the focus ring when you pass focusColor.

AccessKitProvider does not render any visible UI by itself. Add the Accessibility Widget and optionally the Dev Tools inside the same provider so they can read and update the same settings. See Widget and Dev Tool in the sidebar for those components.

Back to documentation