AccessKit

Widget

Persistence

How accessibility preferences chosen in the Widget are saved and restored, and how to configure persistence on the provider.

3 min read

When users change settings in the Widget (e.g. high contrast, reduced motion, font size), those preferences can be saved and restored on their next visit. Persistence is controlled by the provider, not the Widget. With persistence enabled, every change is written to the browser’s local storage and read back when the app loads so the same choices apply across sessions.

What gets persisted

All preferences available in the Widget are persisted when persistence is on: reduced motion, high contrast, enhanced focus indicators, letter spacing, word spacing, line height, font size, dyslexia-friendly font, and color vision mode. The provider saves a single object keyed in local storage; on load it reads that object and applies it before the first paint so the user never sees a flash of default settings.

Enabling and disabling persistence

Persistence is configured on AccessKitProvider with two props:

  • persist — When true (default), user changes are saved to local storage and restored on the next visit. Set to false to keep settings in memory only for the current tab; nothing is written to storage and reloading the page resets to defaults.
  • storageKey — The key used to read and write the settings object in local storage. The default is "accesskit:settings". Change it if you need a separate key per app or environment so settings don’t clash with other code using the same key.

The Widget does not accept persistence props. Users always change settings through the Widget; whether those changes are stored is determined entirely by the provider’s persist and storageKey.

When persistence fails

In some environments localStorage is unavailable, for example, when storage quota is exceeded, in private/incognito browsing on certain browsers, or when storage is disabled by policy. When persist is true and a write fails, the provider:

  1. Stops retrying writes for the rest of the session (to avoid repeated errors).
  2. Logs a warning to the console in development so you're aware during testing.
  3. Calls the optional onPersistError callback (if provided on AccessKitProvider) with the error, so your app can show a toast, log to an error service, or take other action.

Settings continue to work in memory for the current session — the user's changes still apply immediately. Only cross-session persistence is affected.

tsx
import { AccessKitProvider } from "@accesskit/react";
import { AccessibilityWidget } from "@accesskit/react";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AccessKitProvider
          persist={true}
          storageKey="myapp:accessibility"
          onPersistError={(error) => {
              // e.g. show a toast, log to your error service
              console.error("Could not save accessibility preferences:", error)
          }}
        >
          {children}
          <AccessibilityWidget />
        </AccessKitProvider>
      </body>
    </html>
  );
}

When to turn persistence off

Set persist to false when you don’t want preferences to survive reloads or sessions. Typical cases include kiosks or shared devices where each session should start with default settings, or flows that behave like incognito (e.g. guest or temporary sessions). The Widget still works; users can change settings for the current page, but nothing is written to storage and the next visit uses default settings again.

For default values and other provider options, see Configuration. For reading or updating settings in code, see Context & Hooks.

Back to documentation