AccessKit

Core Concepts

Configuration

Configure the AccessKit provider, widget, and dev tools: default settings, persistence, focus color, widget position and styling, and audit rules.

4 min read

AccessKit lets you tailor the provider, the accessibility widget, and the dev tools to your app. This page covers the main configuration options for each piece so you can set defaults, control persistence, match your brand, and tune the audit.


Provider configuration

AccessKitProvider accepts optional props to control initial settings, persistence, and focus styling. Pass them when you wrap your app in the root layout.

  • defaultSettings – A partial object of AccessKitSettings. Any key you omit falls back to the built-in default (e.g. reducedMotion: false, fontSize: 100). Use this to ship with high contrast on, or a different default font size.
  • storageKey – The key used to read and write settings in localStorage. Default is "accesskit:settings". Change it if you need to namespace settings per app or avoid clashes with other code.
  • persist – When true (default), user changes are saved to localStorage and restored on the next visit. Set to false to keep settings in memory only (e.g. for kiosks or incognito-style flows).
  • onPersistError - Optional callback (error: unknown) => void called when a localStorage write fails (e.g. quota exceeded, private browsing). Useful for showing a notification or logging to an error service. In development, a console warning is logged automatically. If the write fails, the provider stops retrying for the session but settings continue to work in memory.
  • focusColor – A CSS color string for the focus ring (e.g. "#0066cc"). Applied as the --accesskit-focus-color custom property on the document so your styles can use it. Omit to use the default blue.
tsx
// app/layout.tsx
import { AccessKitProvider } from "@accesskit/react";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AccessKitProvider
          defaultSettings={{ highContrast: true, fontSize: 110 }}
          storageKey="myapp:accessibility"
          persist={true}
          focusColor="#0066cc"
          onPersistError={(error) => console.error("Settings persistence failed:", error)}
        >
          {children}
        </AccessKitProvider>
      </body>
    </html>
  );
}


All settings (reduced motion, high contrast, enhanced focus, spacing, font size, dyslexia font, color vision) can be set in defaultSettings. Only include the keys you want to override; the rest use built-in defaults.


Widget configuration

AccessibilityWidget supports optional props for position, appearance, and stacking. Place it anywhere inside AccessKitProvider (e.g. in your layout or shell).

  • initialPosition – Where the widget tab is placed on the screen. One of: "bottom-right", "center-right","top-right", "bottom-left", "center-left", "top-left". Default is "center-right". Users can drag the tab to reposition it.
  • style – An object of color overrides so the widget matches your theme. Keys include primary, tabBackground, tabIcon, panelBackground, panelText, border, mutedText, hoverText. Each value is a CSS color string; omit keys to keep defaults.
  • defaultOpen – Whether the widget panel is open on first render. Default is false.
  • zIndex – The stacking order for the widget tab and panel. Default is a high value so it sits above most content; lower it if you have modals or overlays that must appear on top.
tsx
import { AccessibilityWidget } from "@accesskit/react";

export function Layout({ children }: { children: React.ReactNode }) {
  return (
    <>
      {children}
      <AccessibilityWidget
        initialPosition="bottom-right"
        style={{
          primary: "var(--primary)",
          tabBackground: "var(--primary)",
          tabIcon: "#fff",
          panelBackground: "var(--card)",
          panelText: "var(--foreground)",
          border: "var(--border)",
          mutedText: "var(--muted-foreground)",
          hoverText: "var(--foreground)",
        }}
        defaultOpen={false}
        zIndex={9999}
      />
    </>
  );
}


Use CSS variables (e.g. var(--primary)) in style to keep the widget in sync with your design system. The widget remains usable with only the default theme if you omit style.


Dev Tools configuration

AccessKitDevTools is intended for development. Configure where it appears, its stacking order, and which audit rules run in addition to the default WCAG rules.

  • defaultOpen – Whether the dev tools panel is open when the page loads. Default is false.
  • position – Same position options as the widget ("bottom-right", "center-right", etc.). Controls where the dev tools tab is placed.
  • zIndex – Stacking order. Use a value below your widget’s zIndex if you want the widget to stay on top.
  • additionalRules – An array of extra rule tags to run (e.g. ["best-practice", "section508"]). Default runs WCAG 2.x Level A/AA/AAA; add tags like "best-practice"` or category tags (e.g. "cat.color") for broader checks.
tsx
import { AccessKitDevTools } from "@accesskit/react";

export function Layout({ children }: { children: React.ReactNode }) {
  return (
    <>
      {children}
      {process.env.NODE_ENV === "development" && (
        <AccessKitDevTools
          defaultOpen={false}
          position="bottom-right"
          zIndex={9998}
          additionalRules={["best-practice", "section508"]}
        />
      )}
    </>
  );
}


Keep AccessKitDevTools behind a development check (e.g. NODE_ENV === "development") so it is not shipped to production.

For a full list of types and options, see the TypeScript page. For initial setup, see Installation and Quick Start.

Back to documentation