Initialization & Configuration

While A11yCore auto-initializes from the script tag, you can manually initialize for advanced configuration including custom branding, widget positioning, and feature defaults.

Recommended: ESM Bundle

The ESM bundle loads only~14KBinitially (97% smaller than legacy). Features load on-demand when users interact with them.

ESM Initialization (Recommended)

Import the ESM bundle and callA11yCore.init()with your configuration. Features are loaded on-demand as users interact with them.

JavaScript (ESM)

// ESM - Recommended (~14KB initial load)
import A11yCore from 'https://cdn.a11ycore.org/a11ycore/dist/esm/core.js';

await A11yCore.init({
  // Required: Your license key
  licenseKey: 'YOUR_LICENSE_KEY',
  
  // Optional: Enable console logging
  debug: process.env.NODE_ENV !== 'production',
  
  // Optional: Defer widget loading (load manually later)
  lazyWidget: false,
  
  // Optional: Configuration object
  config: {
    // Widget position and behavior
    widget: {
      position: 'bottom-right',  // 'bottom-left', 'top-right', 'top-left'
      offset: { x: 20, y: 20 },
    },
    
    // Branding
    branding: {
      name: 'My Company',
      primaryColor: '#0066CC',
    }
  }
});

// Features are loaded on-demand when users interact with them
// You can also programmatically enable features:
await A11yCore.features.enable('highContrast');
await A11yCore.features.enable('keyboardNav');

Legacy Initialization

If using the legacy script tag, adddata-autoinit="false"to your script tag, then callwindow.A11yCore.init().

JavaScript (Legacy)

// Legacy script tag method
await window.A11yCore.init({
  // Required: Your license key
  licenseKey: 'YOUR_LICENSE_KEY',
  
  // Optional: Enable console logging
  debug: process.env.NODE_ENV !== 'production',
  
  // Optional: Configuration object
  config: {
    // Branding
    branding: {
      name: 'My Company',
      primaryColor: '#0066CC',
      accentColor: '#FF6B35',
      logo: 'https://example.com/logo.svg'
    },
    
    // Widget position and behavior
    widget: {
      position: 'bottom-right',  // 'bottom-left', 'bottom-right', etc.
      offset: { x: 20, y: 20 },
      triggerKey: 'alt+a',
      showBadge: true,
      pulseOnFirstVisit: true
    },
    
    // Default feature settings
    features: {
      keyboardNav: true,
      contentAdjustments: true,
      profiles: ['low-vision', 'cognitive', 'motor']
    },
    
    // User preferences
    defaults: {
      language: 'en',
      rememberSettings: true,
      respectSystemPreferences: true
    },
    
    // Advanced options
    advanced: {
      scanInterval: 5000,         // DOM scan interval in ms
      mutationObserver: true,     // Auto-detect DOM changes
      shadowDomSupport: true,     // Scan Shadow DOM
      iframeSupport: false        // Scan iframes (same-origin)
    },
    
    // Analytics
    analytics: {
      enabled: false,
      endpoint: ''                // Your analytics endpoint
    }
  }
});

Configuration Reference

branding

Customize the widget appearance to match your brand.

Option	Type	Default	Description
name	string	'A11yCore'	Display name in widget header (max 100 chars)
primaryColor	string	'#0066CC'	Primary button/accent color (hex)
accentColor	string	'#FF6B35'	Secondary accent color (hex)
logo	string	''	URL to logo image (must be HTTPS)

widget

Control widget position and trigger behavior.

Option	Type	Default
position	string	'bottom-right'
offset	{x, y}	{x: 20, y: 20}
triggerKey	string	'alt+a'
showBadge	boolean	true
pulseOnFirstVisit	boolean	true

advanced

These settings control DOM scanning behavior. ThemutationObserveroption is recommended for SPAs to detect dynamically added content.

Option	Type	Default	Description
scanInterval	number	5000	Periodic DOM scan interval (ms)
mutationObserver	boolean	true	Auto-detect DOM changes
shadowDomSupport	boolean	true	Scan Shadow DOM trees
iframeSupport	boolean	false	Scan same-origin iframes