Skip to Content
New: AI Sign Language Avatars now in beta! View Sign Language feature ->
Developer ResourcesJavaScript API

WelcomingWeb JavaScript API

Client-side integration · No API key required

Once the WelcomingWeb widget is embedded on your site, a global JavaScript API becomes available at window.AccessibilityWidgetAPI.

Use it to:

  • open and close the widget
  • enable and disable features
  • switch languages
  • activate accessibility profiles
  • listen to lifecycle and UI events from your host application
Open API PlaygroundREST API GuideWebhooks Integration

Overview

  • Global object: window.AccessibilityWidgetAPI
  • Public API: widget control, profiles, features, language, lifecycle
  • Events: callback API and DOM CustomEvent channels
  • Host hooks: react to widget, feature, profile, and language changes

Installation

Embed the widget script

<script
  src="https://cdn-01.welcomingweb.com/a11y-widget.bundle.js"
  data-widget-id="YOUR_WIDGET_ID"
></script>

Wait until the API is ready

window.addEventListener('welcomingweb:widget.loaded', e => {
  console.log('Widget loaded', e.detail)
  window.AccessibilityWidgetAPI.openWidget()
})

Access the global object

window.AccessibilityWidgetAPI

Public methods

Use these methods to control the widget from your host page.

MethodDescription
openWidget()Open the accessibility widget.
closeWidget()Close the accessibility widget.
enableProfile(profileKey)Activate a predefined accessibility profile.
disableCurrentProfile()Disable the currently active profile.
enableFeature(featureKey, mode?, options?)Enable a feature with an optional mode and options.
disableFeature(featureKey)Disable a specific feature.
changeLanguage(langCode)Change the widget language dynamically.
resetAllFeatures()Reset all features to their default disabled state.
resetFeatureEffects()Remove applied effects while preserving preferences where supported.
reinitializeWidget()Tear down and initialize the widget again.
destroy()Completely remove the widget and clear the global API instance.
enableOutsideClickClosing()Enable closing the widget when users click outside it.
disableOutsideClickClosing()Disable closing the widget when users click outside it.
setCloseOnOutsideClick(enabled)Set the outside-click closing behavior.
getCloseOnOutsideClick()Read the current outside-click closing setting.

Widget visibility

window.AccessibilityWidgetAPI.openWidget()
window.AccessibilityWidgetAPI.closeWidget()

Profiles

window.AccessibilityWidgetAPI.enableProfile('visually_impaired')
window.AccessibilityWidgetAPI.disableCurrentProfile()

Features

enableFeature(featureKey, mode?, options?)

  • featureKey — required feature identifier
  • mode — optional mode key for features with multiple modes
  • options — optional configuration object
window.AccessibilityWidgetAPI.enableFeature('contrast', 'invert', {
  brightness: 0.8
})
 
window.AccessibilityWidgetAPI.disableFeature('custom_font')
window.AccessibilityWidgetAPI.resetAllFeatures()
window.AccessibilityWidgetAPI.resetFeatureEffects()

Common examples:

window.AccessibilityWidgetAPI.enableFeature('custom_font', 'dyslexia')
window.AccessibilityWidgetAPI.enableFeature('bigger_text', 'b2')
window.AccessibilityWidgetAPI.enableFeature('highlight_links', 'links')

Language

window.AccessibilityWidgetAPI.changeLanguage('fr')

Related events:

  • language.changeRequested
  • language.changed
  • language.changeFailed

Lifecycle

window.AccessibilityWidgetAPI.reinitializeWidget()
window.AccessibilityWidgetAPI.destroy()
⚠️

After calling reinitializeWidget(), wait for widget.loaded before issuing more widget commands.

Outside click behavior

window.AccessibilityWidgetAPI.enableOutsideClickClosing()
window.AccessibilityWidgetAPI.disableOutsideClickClosing()
 
window.AccessibilityWidgetAPI.setCloseOnOutsideClick(true)
window.AccessibilityWidgetAPI.setCloseOnOutsideClick(false)
 
const enabled = window.AccessibilityWidgetAPI.getCloseOnOutsideClick()
console.log(enabled)

Event subscription API

The widget includes a built-in callback system.

on(eventName, handler)

Subscribe to a specific event. Returns an unsubscribe function.

const unsubscribe = window.AccessibilityWidgetAPI.on(
  'language.changed',
  event => {
    console.log('Language changed', event.language)
  }
)
 
unsubscribe()

off(eventName, handler)

Remove a previously registered handler.

function onOpened(event) {
  console.log('opened', event)
}
 
window.AccessibilityWidgetAPI.on('widget.opened', onOpened)
window.AccessibilityWidgetAPI.off('widget.opened', onOpened)

once(eventName, handler)

Subscribe to an event only once.

window.AccessibilityWidgetAPI.once('widget.loaded', event => {
  console.log('Loaded once', event)
})

onAny(handler)

Listen to all widget events.

const stop = window.AccessibilityWidgetAPI.onAny(event => {
  console.log(event.name, event)
})

DOM event API

In addition to callback subscriptions, the widget dispatches browser CustomEvent events on window.

window.addEventListener('welcomingweb:language.changed', e => {
  console.log(e.detail)
})
  • specific channel: welcomingweb:<eventName>
  • generic channel: welcomingweb:event

Event list

Use these event names with both the callback API and DOM events.

Widget lifecycle

  • widget.loaded
  • widget.opened
  • widget.closed
  • widget.reinitialized
  • widget.reset
  • widget.destroyed

Language

  • language.changeRequested
  • language.changed
  • language.changeFailed

Features

  • feature.enabled
  • feature.disabled

Profiles

  • profile.enabled
  • profile.disabled

Position and behavior

  • widget.positionChanged
  • widget.outsideClickClosingChanged

Event payload format

Each event includes a normalized payload.

{
  "name": "language.changed",
  "timestamp": "2026-03-18T12:34:56.000Z",
  "widgetId": "YOUR_WIDGET_ID",
  "language": "fr",
  "defaultLanguage": "en",
  "url": "https://example.com/pricing",
  "isOpen": true,
  "source": "ui",
  "reason": "api",
  "previousLanguage": "en",
  "isTranslated": true
}
FieldDescription
nameEvent name.
timestampISO timestamp.
widgetIdWidget UUID.
urlCurrent page URL.
languageCurrent selected language, when relevant.
defaultLanguageWidget default language, when available.
isOpenCurrent widget open state.
sourceapi, ui, shortcut, system, or customTrigger.
reasonOptional reason string.

Event-specific fields may also include previousLanguage, isTranslated, featureId, mode, profile, previousProfile, position, enabled, and error.

Script tag configuration options

The widget supports several data-* attributes on the embed script for host-side configuration overrides.

<script
  src="https://cdn-01.welcomingweb.com/a11y-widget.bundle.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-api-url="https://api.welcomingweb.com"
  data-theme="light"
  data-language="en"
  data-widget-display-type="FULL"
  data-desktop-horizontal-position="RIGHT"
  data-desktop-vertical-position="LOWER"
  data-desktop-offset-x="16"
  data-desktop-offset-y="16"
  data-mobile-horizontal-position="RIGHT"
  data-mobile-vertical-position="LOWER"
  data-mobile-offset-x="16"
  data-mobile-offset-y="16"
  data-button-color-mode="SOLID"
  data-button-primary-color="#504CFF"
  data-button-secondary-color="#8F84FF"
  data-button-gradient-direction="TO_BOTTOM_RIGHT"
  data-button-size="MEDIUM"
  data-button-icon-type="WALKING"
  data-enable-custom-trigger="false"
  data-custom-trigger-selector="#open-a11y"
  data-enable-keyboard-shortcuts="true"
  data-style-mode="auto"
  data-requires-consent="functional"
  data-close-on-outside-click="true"
  data-csp-nonce="YOUR_NONCE"
></script>

Display types

  • FULL
  • MINI
  • NANO
  • HEADLESS

Style modes

  • auto
  • host
  • cdn

Supported feature keys and mode keys

Feature availability depends on plan, visibility, rollout status, and server-side configuration.

  • contrast — invert, dark, light
  • saturation — low, high, desaturate
  • custom_color — no mode
  • smart_contrast — no mode (PRO, beta)

Example feature calls:

window.AccessibilityWidgetAPI.enableFeature('contrast', 'invert')
window.AccessibilityWidgetAPI.enableFeature('bigger_text', 'b2')
window.AccessibilityWidgetAPI.enableFeature('custom_font', 'dyslexia')
window.AccessibilityWidgetAPI.enableFeature('highlight_links', 'links')
window.AccessibilityWidgetAPI.enableFeature('screen_reader', 'fast')
window.AccessibilityWidgetAPI.enableFeature('hide_images', 'graphics')

Supported profile keys

The following profile keys are currently defined in the accessibility catalog.

  • blind
  • motor_impaired
  • color_blind
  • visually_impaired
  • seizure_epileptic
  • adhd
  • cognitive_learning
  • elderly
  • dyslexia
  • kids
window.AccessibilityWidgetAPI.enableProfile('dyslexia')

Profile behavior is server-configured and may enable multiple underlying features and modes at once.

Preventing host-page content from being translated

When live site translation is enabled, the widget can translate host-page text nodes and common attributes like placeholder, alt, aria-label, and title.

If you have areas that should never be translated, mark them using one of the following:

  • class: no-translate
  • attribute: data-no-translate
  • attribute: translate="no"
<div class="no-translate">
  Debug logs, JSON payloads, IDs, and raw system messages go here.
</div>
 
<div data-no-translate>
  Internal status output
</div>
 
<div translate="no">
  SKU-1234 / build-2026-03-18 / feature flags
</div>
  • logs and debug consoles
  • JSON payloads and raw API responses
  • IDs, keys, SKUs, tokens, and internal labels
  • admin tools and developer UIs
  • email addresses and URLs when exact output should be preserved

Content already skipped by the translator

  • script
  • style
  • iframe
  • [contenteditable]
  • code
  • pre
  • kbd
  • samp
💡

For dynamic status panels or custom developer consoles, it is still recommended to add data-no-translate or translate=“no” explicitly.

Language and direction hooks added to the document

When translation is active, the widget may update the root document element with accessibility language state.

  • html[data-a11y-active-lang]
  • html.a11y-rtl
  • html.a11y-ltr
html.a11y-rtl .my-custom-sidebar {
  direction: rtl;
}

These hooks are useful if your application wants to align custom UI with the widget’s translated language state.

The widget supports consent-gated initialization.

<script
  src="https://cdn-01.welcomingweb.com/a11y-widget.bundle.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-requires-consent="functional"
></script>

The widget can detect consent through:

  • window.dataLayer
  • a custom browser event
  • the helper function below
window.welcomingWeb.grantConsent()

Recognized consent categories include:

  • functional
  • analytics
  • ad
  • personalization
  • security

Use your own trigger button

You can open the widget from your own existing UI by enabling a custom trigger.

<button id="open-a11y">Accessibility options</button>
 
<script
  src="https://cdn-01.welcomingweb.com/a11y-widget.bundle.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-enable-custom-trigger="true"
  data-custom-trigger-selector="#open-a11y"
></script>

When a custom trigger is enabled and found, the internal floating button is hidden and your external trigger controls the widget.

Keyboard shortcut

When keyboard shortcuts are enabled, the widget supports Alt + Shift + A to toggle the widget open and closed.

<script
  src="https://cdn-01.welcomingweb.com/a11y-widget.bundle.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-enable-keyboard-shortcuts="true"
></script>

Async behavior notes

Some API calls perform asynchronous work internally, especially feature application and language changes.

  • enableFeature(...)
  • disableFeature(...)
  • enableProfile(...)
  • disableCurrentProfile()
  • changeLanguage(...)

After calling reinitializeWidget(), wait for the widget to finish loading again before calling more widget methods.

window.AccessibilityWidgetAPI.reinitializeWidget()
 
window.AccessibilityWidgetAPI.once('widget.loaded', () => {
  window.AccessibilityWidgetAPI.changeLanguage('fr')
})

API usage examples

Open the widget from your own button

<button id="open-a11y">Accessibility options</button>
<script>
  document.getElementById('open-a11y').addEventListener('click', () => {
    window.AccessibilityWidgetAPI.openWidget()
  })
</script>

Enable a feature from your own UI

<button id="invert-contrast">Enable contrast</button>
<script>
  document.getElementById('invert-contrast').addEventListener('click', () => {
    window.AccessibilityWidgetAPI.enableFeature('contrast', 'invert')
  })
</script>

Disable a feature from your own UI

<button id="disable-font">Disable custom font</button>
<script>
  document.getElementById('disable-font').addEventListener('click', () => {
    window.AccessibilityWidgetAPI.disableFeature('custom_font')
  })
</script>

Sync your site language selector

const siteLanguageSelect = document.getElementById('site-language')
 
siteLanguageSelect.addEventListener('change', e => {
  window.AccessibilityWidgetAPI.changeLanguage(e.target.value)
})
 
window.AccessibilityWidgetAPI.on('language.changed', event => {
  console.log('Widget language now', event.language)
})

React to user language changes from the widget UI

window.AccessibilityWidgetAPI.on(
  'language.changed',
  ({ language, previousLanguage, source }) => {
    console.log('User changed language', {
      language,
      previousLanguage,
      source
    })
 
    if (source === 'ui') {
      document.documentElement.setAttribute('data-widget-language', language)
    }
  }
)

React to any user action

window.AccessibilityWidgetAPI.onAny(event => {
  if (event.source === 'ui') {
    console.log('User action from widget UI', event.name, event)
  }
})

Analytics example

window.AccessibilityWidgetAPI.onAny(event => {
  window.dataLayer = window.dataLayer || []
  window.dataLayer.push({
    event: 'welcomingweb_api_event',
    widgetEventName: event.name,
    widgetEventSource: event.source,
    widgetId: event.widgetId,
    widgetLanguage: event.language || null
  })
})

Wait for widget load, then open

window.AccessibilityWidgetAPI.once('widget.loaded', () => {
  window.AccessibilityWidgetAPI.openWidget()
})
 
window.addEventListener('welcomingweb:widget.loaded', () => {
  window.AccessibilityWidgetAPI.openWidget()
})

Common integration patterns

Use your own menu

function openAccessibilityMenu() {
  window.AccessibilityWidgetAPI.openWidget()
}
 
function activateDyslexiaMode() {
  window.AccessibilityWidgetAPI.enableProfile('dyslexia')
}

Keep host UI in sync

window.AccessibilityWidgetAPI.on('widget.opened', () => {
  document.body.classList.add('a11y-widget-open')
})
 
window.AccessibilityWidgetAPI.on('widget.closed', () => {
  document.body.classList.remove('a11y-widget-open')
})

Watch feature toggles

window.AccessibilityWidgetAPI.on('feature.enabled', ({ featureId, mode }) => {
  console.log('Enabled', featureId, mode)
})
 
window.AccessibilityWidgetAPI.on('feature.disabled', ({ featureId }) => {
  console.log('Disabled', featureId)
})

Troubleshooting

window.AccessibilityWidgetAPI is undefined

  • Ensure the script is embedded before you call the API.
  • Ensure data-widget-id is valid and active.
  • Ensure the widget has finished loading.
  • Ensure no script loading or CSP issue blocks the bundle.
window.addEventListener('welcomingweb:widget.loaded', () => {
  console.log('Widget ready')
})

My callback does not fire

  • You subscribed after the event already happened.
  • The event name is spelled exactly as documented.
  • Your code runs after the widget script has initialized.
window.AccessibilityWidgetAPI.onAny(event => {
  console.log('Debug event', event.name, event)
})

The widget loads, but widget.loaded is missed

Prefer a window DOM listener or initialize your subscriptions before the widget bundle finishes loading.

window.addEventListener('welcomingweb:widget.loaded', handler)

Quick reference

window.AccessibilityWidgetAPI.openWidget()
window.AccessibilityWidgetAPI.closeWidget()
window.AccessibilityWidgetAPI.enableProfile('visually_impaired')
window.AccessibilityWidgetAPI.disableCurrentProfile()
window.AccessibilityWidgetAPI.enableFeature('contrast', 'invert', {
  brightness: 0.8
})
window.AccessibilityWidgetAPI.disableFeature('contrast')
window.AccessibilityWidgetAPI.changeLanguage('es')
window.AccessibilityWidgetAPI.resetAllFeatures()
window.AccessibilityWidgetAPI.resetFeatureEffects()
window.AccessibilityWidgetAPI.reinitializeWidget()
window.AccessibilityWidgetAPI.destroy()
Last updated on
Developer ResourcesRest Api Guide