JavaScript widget

JavaScript configuration reference

Every property available in window._cyA11yConfig, its type, accepted values, and default. Scope: this page applies to the direct JavaScript embed — sites that…

Updated August 6, 2026

Scope: this page applies to the direct JavaScript embed — sites that set window._cyA11yConfig inline before the widget script tag. It does not apply to the WordPress plugin (configured in wp-admin) or the SaaS/CDN embed (configured in the dashboard — remote configuration there overrides anything set inline).

The widget reads configuration from the global window._cyA11yConfig object once, at the moment the script loads. Set this object before the widget script tag. Any property you omit falls back to its default value.

Provide nested objects complete. Top-level properties are replaced, not deep-merged — only keyboard and modules merge with their defaults. If you override status, position, or margins, include every key of that object. A margins object missing the mobile block stops the button rendering on mobile entirely; a status object with only one device key disables the widget on the other device.

Full configuration object

The object below is the complete shape the script reads, with all defaults.

window._cyA11yConfig = {

  // ── Device visibility ─────────────────────────────────
  status: {
    desktop: true,           // render the widget on desktop
    mobile:  true,           // render the widget on mobile
  },

  // ── Appearance ────────────────────────────────────────
  iconId:       'default',   // 'default' | 'accessibility' | 'assist' | 'wheel'
  primaryColor: '#1863DC',   // button colour — 6-digit hex only
  iconSize:     48,          // button diameter in pixels (number)
  label: 'Accessibility widget', // accessible name (screen readers)

  // ── Position ──────────────────────────────────────────
  position: {
    desktop: 'bottom-right', // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
    mobile:  'bottom-right',
  },
  margins: {                 // distance from screen edges, px
    desktop: { top: 20, bottom: 20, left: 20, right: 20 },
    mobile:  { top: 20, bottom: 20, left: 20, right: 20 },
  },

  // ── Language ──────────────────────────────────────────
  language: {
    default:  'en',  // fallback when the page/browser language is unsupported
    selected: [],    // currently not used — see Language section
  },

  // ── Keyboard shortcut ─────────────────────────────────
  keyboard: {
    enabled:  false,
    shortcut: 'alt+a', // 'alt' | 'ctrl' | 'shift' + a–z, 0–9, f1–f12, space
  },

  // ── Modules ───────────────────────────────────────────
  // Every tool is an { enabled: boolean } object, grouped by panel
  // section. All tools are enabled by default.
  modules: {
    color: {
      darkContrast:    { enabled: true },
      lightContrast:   { enabled: true },
      highContrast:    { enabled: true },
      highSaturation:  { enabled: true },
      lowSaturation:   { enabled: true },
      monochrome:      { enabled: true },
    },
    content: {
      adjustFontSizing: { enabled: true },
      highlightTitle:   { enabled: true },
      highlightLinks:   { enabled: true },
      dyslexicFont:     { enabled: true },
      letterSpacing:    { enabled: true },
      lineHeight:       { enabled: true },
      fontWeight:       { enabled: true },
      textAlign:        { enabled: true },
    },
    navigation: {
      readingGuide:     { enabled: true },
      pauseAnimations:  { enabled: true },
      bigCursor:        { enabled: true },
    },
    statement:  { enabled: false, url: '' },
    profiles:   { enabled: true },  // whole profiles section on/off
    pageRead:   { enabled: true },
    muteSounds: { enabled: true },
  },
};

Property reference

status

Exists and controls whether the widget renders at all, per device type. Turns the widget on or off per device. When the current device’s flag is false, the button is not rendered on that device.

Property	Type	Default
`status.desktop`	boolean	`true`
`status.mobile`	boolean	`true`

Provide both keys when overriding — a missing key is treated as disabled, not as its default.

iconId

The icon displayed inside the widget button. An unrecognised value falls back to the default icon.

Value	Description
`'default'`	Standard accessibility person icon (default)
`'accessibility'`	Accessibility figure, alternate style
`'assist'`	Assistive-hand icon
`'wheel'`	Wheelchair symbol

primaryColor

The background colour of the floating widget button, as a 6-digit hex value.

Property	Type	Default
`primaryColor`	string (6-digit hex)	`'#1863DC'`

The widget computes focus-ring and shadow colours from this value to keep keyboard focus visible. Three-digit shorthand (#F00) and non-hex formats break that computation — the button still shows your colour, but focus indicators fall back to black. Always use the full six digits.

The button icon is white. Choose a colour with at least a 3:1 contrast ratio against white to meet WCAG 2.1 AA for UI components. You can check ratios at webaim.org/resources/contrastchecker.

iconSize

The diameter of the floating button in pixels.

Property	Type	Default	Minimum recommended
`iconSize`	number	`48`	`44`

WCAG 2.5.8 (Target Size, AA) requires a minimum touch target of 24×24 px; WCAG 2.5.5 (AAA) recommends 44×44 px. The default 48 px exceeds both. Only reduce the size if space is genuinely constrained.

label

The accessible name of the widget button, announced by screen readers when a visitor focuses the button. Not visible on screen.

Property	Type	Default
`label`	string	`'Accessibility widget'`

Change this if your site is in a language other than English — for example 'Widget d'accessibilité' for a French-language site.

position

Controls which corner the floating button occupies. Desktop and mobile are set independently.

Value	Description
`'bottom-right'`	Bottom-right corner (default)
`'bottom-left'`	Bottom-left corner
`'top-right'`	Top-right corner
`'top-left'`	Top-left corner

An unrecognised value falls back to 'bottom-left' (not the bottom-right default). When overriding, set both desktop and mobile — see the note at the top of this page.

margins

The distance in pixels from the button to the screen edges. Only the two edges matching the chosen corner apply — with position: 'bottom-right', the bottom and right values are used.

margins: {
  desktop: { top: 20, bottom: 20, left: 20, right: 20 },
  mobile:  { top: 20, bottom: 20, left: 20, right: 20 },
}

Property	Type	Default
`margins.desktop.top / bottom / left / right`	number	`20`
`margins.mobile.top / bottom / left / right`	number	`20`

Provide all four edges, for both devices. A partial margins object is not merged with defaults. If the current device’s block is missing, the button fails to render on that device. Increase values if the widget overlaps a sticky footer, cookie banner, or chat launcher; 16–40 px is typical.

language

Controls the widget’s display language.

language: {
  default:  'en',
  selected: [],
}

Property	Type	Default	Description
`language.default`	string (language code)	`'en'`	Used when the detected page/browser language is not supported. Final fallback is English.
`language.selected`	string[]	`[]`	Currently has no effect — see note below.

The language resolution order is: 1) the page’s detected language (from the document/browser), if supported → 2) language.default, if supported → 3) English. A visitor’s manual choice in the widget’s language switcher is saved in the browser and takes precedence on return visits.

language.selected currently has no effect on the switcher. The switcher always appears and lists all 58 supported languages, with a search box.

Supported languages

The widget supports exactly 58 languages:

Code	Language	Code	Language
`am`	Amharic	`ms`	Malay
`ar`	Arabic	`my`	Burmese
`bg`	Bulgarian	`nb`	Norwegian Bokmål
`bn`	Bengali	`nl`	Dutch
`ca`	Catalan	`no`	Norwegian
`cs`	Czech	`pa`	Punjabi
`da`	Danish	`pl`	Polish
`de`	German	`pt`	Portuguese
`el`	Greek	`ro`	Romanian
`en`	English	`ru`	Russian
`es`	Spanish	`si`	Sinhala
`fa`	Persian	`sk`	Slovak
`fi`	Finnish	`sl`	Slovenian
`fil`	Filipino	`sr`	Serbian
`fr`	French	`sr-SP`	Serbian Cyrillic
`gl`	Galician	`sv`	Swedish
`he`	Hebrew	`sw`	Swahili
`hi`	Hindi	`ta`	Tamil
`hr`	Croatian	`te`	Telugu
`hu`	Hungarian	`th`	Thai
`id`	Indonesian	`tr`	Turkish
`it`	Italian	`uk`	Ukrainian
`ja`	Japanese	`ur`	Urdu
`ka`	Georgian	`vi`	Vietnamese
`kn`	Kannada	`zh-Hans`	Chinese, Simplified
`ko`	Korean	`zh-Hant`	Chinese, Traditional
`ku`	Kurdish
`lb`	Luxembourgish
`lt`	Lithuanian
`lv`	Latvian
`ml`	Malayalam
`mn`	Mongolian

keyboard

Registers a keyboard shortcut that opens the widget without clicking the button.

keyboard: {
  enabled:  true,
  shortcut: 'alt+a',
}

Property	Type	Default	Description
`keyboard.enabled`	boolean	`false`	Whether the shortcut is active
`keyboard.shortcut`	string	`'alt+a'`	Modifier(s) + key, joined with `+`

Accepted modifiers are alt, ctrl, and shift, in any combination ('ctrl+shift+k'). The final part is the key: a letter a–z, a digit 0–9, a function key f1–f12, or space. The Cmd/Meta key is not supported. On macOS, alt is the Option key.

Matching is exact — 'alt+a' does not fire on Ctrl+Alt+A — and layout-independent, so the shortcut works the same on non-QWERTY keyboards. The shortcut is ignored while the visitor is typing in a form field or editable area.

Choose a combination that does not conflict with browser or operating-system shortcuts on your target platforms. A shortcut makes the widget discoverable for keyboard users without tabbing to the button — especially useful on long pages.

modules.statement

Controls the accessibility-statement link shown in the widget footer.

modules: {
  statement: {
    enabled: true,
    url: 'https://example.com/accessibility-statement/',
  },
}

Property	Type	Default	Description
`modules.statement.enabled`	boolean	`false`	Show the statement link in the widget
`modules.statement.url`	string	`''`	Full URL of your accessibility statement

An accessibility statement is required for public-sector websites in the UK and EU and is considered best practice for any organisation publicly demonstrating accessibility compliance.

With enabled: true and an empty url, the link still appears and points to #. Always provide a URL when enabling this module.

modules — tool visibility

Controls which tools appear in the widget panel. Set a tool’s enabled to false to hide it from all visitors. All tools are enabled by default. When every tool in a group is disabled, that whole panel section is removed.

modules: {
  content:    { adjustFontSizing: { enabled: false } }, // hide one tool
  navigation: { bigCursor:        { enabled: false } },
}

Important: hiding a tool prevents all visitors from using it, including those who rely on it. Only disable a tool if it causes a genuine technical conflict with your site. Hiding tools because they alter your visual design is not recommended.

Colour and contrast — modules.color

Key	Default	What it does
`darkContrast`	`{ enabled: true }`	Dark background, light text
`lightContrast`	`{ enabled: true }`	Light background, dark text
`highContrast`	`{ enabled: true }`	Maximum contrast between text and background
`highSaturation`	`{ enabled: true }`	Increases colour intensity
`lowSaturation`	`{ enabled: true }`	Reduces colour intensity
`monochrome`	`{ enabled: true }`	Strips all colour from the page

Content adjustments — modules.content

Key	What it does
`adjustFontSizing`	Lets visitors increase or decrease text size
`dyslexicFont`	Switches to a dyslexia-friendly typeface
`highlightTitle`	Adds visual emphasis to headings
`textAlign`	Lets visitors realign page text
`highlightLinks`	Underlines and highlights all links
`letterSpacing`	Increases spacing between characters
`lineHeight`	Increases spacing between lines
`fontWeight`	Increases font weight for improved legibility

Navigation tools — modules.navigation

Key	Default	What it does
`readingGuide`	`{ enabled: true }`	Overlays a horizontal line that follows the cursor
`pauseAnimations`	`{ enabled: true }`	Stops CSS animations and transitions
`bigCursor`	`{ enabled: true }`	Replaces the default cursor with a larger one

modules.profiles

One switch controls the whole profiles section — profiles cannot be toggled individually.

Property	Type	Default	Description
`modules.profiles.enabled`	boolean	`true`	Set to `false` to remove the entire profiles section from the panel

The profiles shown when the section is enabled:

Profile	What it does
Low Vision	Increases font size, contrast, and cursor size
ADHD	Reduces distractions and focuses the reading area
Seizure Safe	Reduces flashing colours and motion
Epilepsy Safe Mode	Dampens colour and stops flashing animations

Read aloud & sound — modules.pageRead, modules.muteSounds

Property	Type	Default	What it does
`modules.pageRead.enabled`	boolean	`true`	Read-page-aloud tool in the navigation section
`modules.muteSounds.enabled`	boolean	`true`	Mute-sounds tool in the navigation section

Minimal embed example

Only position and language configured; everything else uses defaults.

html

<script>
(function(w,d,s,u){
  w._cyA11yConfig = {
    position: { desktop: 'bottom-left', mobile: 'bottom-left' },
    language: { default: 'fr', selected: [] },
  };
  var js = d.createElement(s), fjs = d.getElementsByTagName(s)[0];
  js.src = u;
  js.async = true;
  fjs.parentNode.insertBefore(js, fjs);
})(window, document, 'script',
   'https://cdn-cookieyes.com/widgets/accessibility.js');
</script>

Full configuration example