API reference

Every option, theme key, method and export of the package, with its type and default.

On this page

Options

Passed to init(options), as props of AccessibilityWidget, or later to widget.setOptions(options).

Options
Name	Type	Default	Description
`position`	`"left" \| "right"`	`"left"`	Screen side of the launcher and panel.
`offset`	`{ x?: number; y?: number }`	`{ x: 24, y: 24 }`	Distance from the screen edges, in px (0–1000).
`theme`	`AccessibilityTheme`		Colors, radius and font: see Theme below.
`colorScheme`	`"auto" \| "light" \| "dark"`	`"auto"`	Light or dark panel. "auto" follows the page: dark while the site's own background is dark, however the site switches themes. Panel colors set in theme turn "auto" off.
`icon`	`string \| Element`	`built-in icon`	Launcher logo: an image URL or a DOM element. Pass only trusted elements: they are cloned as they are.
`logo`	`string \| Element \| null`	`hidden`	Logo next to the panel title.
`buttonSize`	`number`	`56`	Launcher diameter, in px (24–160).
`features`	`Partial<Record<FeatureKey, boolean>>`	`all on`	Set a control to `false` to remove it. A removed setting stays off.
`initialSettings`	`Partial<AccessibilitySettings>`		Settings for visitors with nothing saved.
`languages`	`AccessibilityLanguage[] \| false`	`English + Arabic`	Entries of the language menu, or `false` to hide the menu.
`language`	`string`	`saved → <html lang> → first`	Starting language code.
`labels`	`Partial<AccessibilityLabels>`		Override single strings on top of the active language.
`dir`	`"ltr" \| "rtl"`	`language's direction`	Force the widget's text direction.
`shortcut`	`string \| false`	`"Alt+A"`	Shortcut that opens and closes the panel and brings the widget back after “Hide widget”. With `false`, the hide button is removed.
`statementUrl`	`string`		Link to your accessibility statement in the panel's footer (http, https or relative).
`feedbackUrl`	`string`		Where visitors report an accessibility problem (a page, a form or `mailto:`), shown in the panel's footer.
`showSkipLink`	`boolean`	`true`	A “Skip to main content” link. Left out when the page has no `main` or `h1`, or already starts with its own skip link.
`zIndex`	`number`	`2147483000`	Stacking order of the widget.
`persist`	`boolean`	`true`	Save settings in localStorage, kept in sync across tabs.
`storageKey`	`string`	`"a11yw-settings"`	localStorage key.
`nonce`	`string`		CSP nonce for the injected `style` tags.
`onChange`	`(settings) => void`		Called when the visitor changes something.

Theme

The keys of the theme option. Colors take any CSS color; only hex colors are checked for contrast.

Theme
Name	Type	Description
`primary`	`string`	Brand color: launcher, header and active states.
`onPrimary`	`string`	Text and icon color on top of primary.
`background`	`string`	Panel background.
`surface`	`string`	Footer, segmented controls and hover states.
`text, mutedText`	`string`	Text and secondary text.
`border`	`string`	Borders.
`radius`	`number \| string`	Corner radius: a number in px or any CSS length.
`fontFamily`	`string`	Font stack of the panel.

Instance methods

init() returns the widget. The script-tag build exposes the same exports on window.A11yWidget.

TypeScript

import { init } from "open-accessibility-widget";

const widget = init();

widget.open(); widget.close(); widget.toggle();
widget.getSettings();                                  // a frozen snapshot
widget.setSettings({ fontSize: 120 });                 // validated: bad values are dropped
widget.setSettings((s) => ({ fontSize: s.fontSize + 10 }));
widget.toggleProfile("visionImpaired");
widget.reset();
widget.setOptions({ theme: { primary: "#000000" }, language: "ar" });
const unsubscribe = widget.subscribe(({ settings, isOpen }) => {});
widget.destroy();                                      // removes the widget and undoes every change

Instance methods
Name	Type	Description
`open(), close(), toggle()`	`void`	Open, close or toggle the panel.
`getSettings()`	`AccessibilitySettings`	The current settings, as a frozen snapshot.
`getState()`	`AccessibilityState`	The settings and whether the panel is open.
`setSettings(update)`	`void`	Merge changes: an object, or a function of the previous settings. Input is validated and invalid values are dropped. Setting `profiles` applies their adjustments too.
`toggleProfile(id)`	`void`	Turn a profile on or off.
`reset()`	`void`	Return every adjustment to the page as authored.
`setOptions(options)`	`void`	Change appearance and behaviour options at runtime.
`subscribe(listener)`	`() => void`	Listen to settings and open-state changes. Returns a function that stops listening.
`destroy()`	`void`	Remove the widget and undo every change it made to the page.

React

From open-accessibility-widget/react, which also re-exports everything else. The entry is marked "use client".

React
Name	Type	Description
`<AccessibilityWidget {...options} />`	`null`	Mounts the widget with these options. Changed props call `setOptions()`; unmounting removes the widget. Renders nothing itself.
`useAccessibility()`	`{ settings, isOpen, widget }`	Read and control the widget from any component. `widget` is `null` until it mounts.

Exports

Named exports of the package.

Exports
Name	Type	Description
`init(options), createAccessibilityWidget(options)`	`AccessibilityWidgetInstance`	Mount the widget on `body` and return it. Calling it again replaces the existing widget.
`getAccessibilityWidget()`	`AccessibilityWidgetInstance \| null`	The widget that is running, if any.
`onActiveWidgetChange(listener)`	`() => void`	Listen for a widget being created or destroyed. Returns a function that stops listening.
`DEFAULT_SETTINGS`	`Readonly<AccessibilitySettings>`	Every setting at its default.
`RANGES`	`Record<RangeKey, { min, max, step }>`	Minimum, maximum and step of each percentage setting.
`PROFILE_IDS, PROFILE_PRESETS`	`ProfileId[], Record<ProfileId, ProfilePreset>`	The profile ids, and the adjustments each profile switches on.
`sanitizeSettings(input)`	`AccessibilitySettings`	Validate untrusted input into complete settings.
`builtInLanguages`	`AccessibilityLanguage[]`	English and Arabic, to extend with your own languages.
`defaultLabels, arabicLabels`	`AccessibilityLabels`	The English and Arabic strings.

Settings

What getSettings() returns, and what setSettings() and initialSettings accept. Percentages use 100 for unchanged; values outside the range are clamped and unknown values dropped.

Settings
Name	Type	Default	Description
`profiles`	`ProfileId[]`	`[]`	Active profiles, in the order they were turned on.
`contentScale`	`number (50–200)`	`100`	Page zoom, in percent.
`fontSize`	`number (50–200)`	`100`	Text size, in percent.
`lineHeight`	`number (100–200)`	`100`	Line spacing, in percent.
`letterSpacing`	`number (100–200)`	`100`	Letter spacing, in percent (not applied to Arabic).
`textAlign`	`"default" \| "left" \| "center" \| "right" \| "justify"`	`"default"`	Text alignment.
`readableFont`	`boolean`	`false`	A plain, readable font.
`boldText`	`boolean`	`false`	All page text in bold.
`highlightTitles, highlightLinks`	`boolean`	`false`	Outline headings / links.
`textMagnifier`	`boolean`	`false`	Shows the text under the pointer or focus, enlarged (an image's alt text for images).
`readAloud`	`boolean`	`false`	A click, tap or keyboard focus reads that block aloud with the browser's own speech, in the page's language. Escape stops it.
`colorMode`	`"default" \| "dark-contrast" \| "light-contrast" \| "high-contrast"`	`"default"`	Contrast mode.
`saturationMode`	`"default" \| "monochrome" \| "low-saturation" \| "high-saturation"`	`"default"`	Saturation filter.
`invertColors`	`boolean`	`false`	Inverts the page's colors; images and video keep theirs.
`textColor, titleColor, backgroundColor`	`"#rrggbb" \| null`	`null`	Custom text, heading and background colors.
`muteSounds, hideImages, stopAnimations`	`boolean`	`false`	Mute media, hide images, stop CSS animations.
`readingGuide, readingMask`	`boolean`	`false`	Reading line and focus window.
`highlightFocus, highlightHover`	`boolean`	`false`	Strong outline on keyboard focus / on hover.
`cursor`	`"default" \| "black" \| "white"`	`"default"`	Large cursor.

Package contents

Each entry ships ESM, CommonJS and type declarations. No runtime dependencies.

Package contents
Name	Type	Description
`open-accessibility-widget`	`ESM + CJS + .d.ts`	Any framework, or plain JavaScript with a bundler.
`open-accessibility-widget/react`	`ESM + CJS + .d.ts`	React component and hook; `react` 18 or later is an optional peer dependency.
`open-accessibility-widget/languages`	`ESM + CJS + .d.ts`	Optional extra languages (14), tree-shakable, about 1 KB gzipped each.
`dist/open-accessibility-widget.global.js`	`IIFE`	Script-tag build, about 27 KB gzipped; exposes `window.A11yWidget`.
`dist/open-accessibility-widget.languages.global.js`	`IIFE`	Script-tag language pack, about 17 KB gzipped; exposes `window.A11yWidgetLanguages`.

Edit this page on GitHub