@disruptica/ladybug-widget

Embeddable chat widget for Ladybug. Drop it into any website via a script tag, ES module import, or Web Components.

Installation

npm install @disruptica/ladybug-widget

Or load directly from a CDN (no install needed):

<!-- IIFE — classic script tag -->
<script src="https://cdn.jsdelivr.net/npm/@disruptica/ladybug-widget@latest/dist/widget.js"></script>

<!-- ESM — modern browsers -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@disruptica/ladybug-widget@latest/dist/widget.esm.js"></script>

<!-- Web Components -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@disruptica/ladybug-widget@latest/dist/widget.elements.js"></script>

Usage

Script tag (zero config)

Add data-embed-key to the script tag and the widget auto-initializes with a floating launcher button.

<script
  src="https://cdn.jsdelivr.net/npm/@disruptica/ladybug-widget@latest/dist/widget.js"
  data-embed-key="emb_xxx"
  data-position="bottom-right"
  data-primary-color="#4f46e5"
  data-mode="system"
></script>

Programmatic API (ESM)

import { LadybugWidget } from '@disruptica/ladybug-widget';

const widget = new LadybugWidget({
  embedKey: 'emb_xxx',
  position: 'bottom-right',   // or 'bottom-left'
  primaryColor: '#4f46e5',
  mode: 'system',             // 'light' | 'dark' | 'system'
  launcherLabel: 'Get help',
  showLauncher: true,
});

widget.open();
widget.close();
widget.toggle();
widget.destroy();

The widget automatically detects the origin from the script tag or current page URL.

Hide the launcher, trigger manually

const widget = new LadybugWidget({
  embedKey: 'emb_xxx',
  showLauncher: false,
});

document.getElementById('my-button').addEventListener('click', () => {
  widget.toggle();
});

data-* click delegation

No JS needed — use data-ladybug-toggle, data-ladybug-open, or data-ladybug-close on any element:

<button data-ladybug-toggle="emb_xxx">Open chat</button>
<button data-ladybug-close="emb_xxx">Close chat</button>

Web Components

<script type="module" src="https://cdn.jsdelivr.net/npm/@disruptica/ladybug-widget@latest/dist/widget.elements.js"></script>

<!-- Animated launcher button -->
<ladybug-button embed-key="emb_xxx" color="#4f46e5" mode="system"></ladybug-button>

<!-- Headless widget (controlled via attribute) -->
<ladybug-chat embed-key="emb_xxx" color="#4f46e5"></ladybug-chat>
<button onclick="document.querySelector('ladybug-chat').open()">Open</button>

Identify logged-in users

Pass a short-lived signed token from your backend so Ladybug can associate widget sessions with real users. Generate the token using @disruptica/ladybug-identity.

// Static token
new LadybugWidget({
  embedKey: 'emb_xxx',
  userToken: await fetchTokenFromYourBackend(),
});

// Dynamic provider (refreshed automatically)
new LadybugWidget({
  embedKey: 'emb_xxx',
  getUserToken: async () => {
    const res = await fetch('/api/ladybug-token');
    const { token } = await res.json();
    return token;
  },
});

Listen to state changes

document.addEventListener('ladybug:change', (e) => {
  const { open, embedKey } = e.detail;
  console.log(`Widget ${embedKey} is now ${open ? 'open' : 'closed'}`);
});

Utility helpers

import { getWidget, getOrCreateWidget, closeAll } from '@disruptica/ladybug-widget';

const widget = getWidget('emb_xxx');   // undefined if not created yet
const widget2 = getOrCreateWidget({ embedKey: 'emb_xxx' });
closeAll();

Configuration

| Option | Type | Default | Description | |---|---|---|---| | embedKey | string | required | Your embed key (emb_xxx) | | position | "bottom-right" \| "bottom-left" | "bottom-right" | Launcher position | | launcherLabel | string | "Request a change" | Button label | | primaryColor | string | "#4f46e5" | Hex accent color | | mode | "light" \| "dark" \| "system" | "system" | Color mode | | showLauncher | boolean | true | Show the floating launcher button | | userToken | string | — | Signed identity token | | getUserToken | () => Promise<string \| null> | — | Async token provider |

License

MIT