@astralibx/chat-widget

Embeddable visitor-facing chat widget built with Lit Web Components. Framework-agnostic -- works in React, Vue, Angular, or vanilla HTML. Includes a configurable pre-chat funnel (welcome, FAQ, guided questions, form, agent selector), offline handling, post-chat feedback, theming, and real-time events.

Install

npm install @astralibx/chat-widget

Peer Dependencies

| Package | Required | |---------|----------| | socket.io-client | Yes (^4.0.0) |

npm install socket.io-client

Quick Start

HTML

<script type="module">
  import '@astralibx/chat-widget';
</script>

<alx-chat-widget
  socket-url="https://chat.example.com"
  channel="website"
  theme="dark"
  position="bottom-right"
></alx-chat-widget>

Programmatic

import { AlxChatWidget } from '@astralibx/chat-widget';

const widget = document.querySelector('alx-chat-widget') as AlxChatWidget;
widget.configure({
  socketUrl: 'https://chat.example.com',
  channel: 'website',
  theme: 'auto',  // 'dark' | 'light' | 'auto' (follows OS preference)
  position: 'bottom-right',
  user: { userId: '123', name: 'John', email: '[email protected]' },
  branding: { primaryColor: '#D4AF37', companyName: 'Acme', logoUrl: '/logo.png' },
  features: { soundNotifications: true, typingIndicator: true, readReceipts: true },
});

Pre-Chat Flow

widget.configure({
  socketUrl: 'https://chat.example.com',
  channel: 'website',
  preChatFlow: {
    enabled: true,
    skipToChat: true,
    completionAction: 'chat',
    steps: [
      { type: 'welcome', title: 'Hi there!', subtitle: 'How can we help?', showOnlineStatus: true, starters: ['Reset password', 'Business hours', 'Billing help', 'Track order'] },
      {
        type: 'faq',
        searchEnabled: true,
        categories: [{ key: 'billing', label: 'Billing' }, { key: 'technical', label: 'Technical' }],
        items: [
          { question: 'How do I reset my password?', answer: 'Go to Settings > Security > Reset Password.', category: 'technical' },
          { question: 'What payment methods do you accept?', answer: 'Visa, Mastercard, PayPal.', category: 'billing' },
        ],
        showChatPrompt: true,
      },
      {
        type: 'guided',
        mode: 'sequential',
        questions: [
          { key: 'topic', text: 'What do you need help with?', options: [
            { value: 'billing', label: 'Billing' },
            { value: 'technical', label: 'Technical Issue' },
            { value: 'other', label: 'Something Else', skipToStep: 'chat' },
          ]},
        ],
      },
      { type: 'form', title: 'Quick info', fields: [
        { key: 'name', label: 'Name', type: 'text', required: true },
        { key: 'email', label: 'Email', type: 'email', required: true },
      ]},
    ],
  },
});

FAQ-Only Mode

Use the widget as a standalone help center without live chat:

widget.configure({
  socketUrl: 'https://chat.example.com',
  channel: 'website',
  features: { liveChatEnabled: false },
  preChatFlow: {
    enabled: true,
    completionAction: 'close',
    skipToChat: false,
    steps: [
      { type: 'welcome', title: 'Help Center' },
      { type: 'faq', items: [...], showChatPrompt: false },
    ],
  },
});

Events

Track widget interactions with CustomEvents:

const widget = document.querySelector('alx-chat-widget');
widget.addEventListener('chat:session-started', (e) => {
  analytics.track('chat_started', e.detail);
});
widget.addEventListener('chat:faq-viewed', (e) => {
  analytics.track('faq_viewed', { question: e.detail.question });
});

Features

• Configurable pre-chat flow -- Welcome screen, FAQ, guided questions, contact form, and agent selector steps in any order. Details
• FAQ-only mode -- Use the widget as a standalone help center without live chat. Details
• Conversation starters -- Clickable starter chips on the welcome screen to kick off common topics. Details
• Message status indicators -- Visual sending/sent/delivered/read/failed lifecycle with retry support. Details
• Message grouping -- iMessage-style consecutive message grouping with date separators. Details
• Launcher tooltip -- Preview tooltip for unread messages when the widget is closed. Details
• Theming -- Dark, light, and auto themes with full CSS custom property override support. Details
• Offline handling -- Configurable offline form, message, or auto-hide behavior. Details
• Post-chat feedback -- Rating or survey collection after chat ends. Details
• Real-time events -- CustomEvents for widget open/close, messages, sessions, FAQ interactions, escalation, and feedback. Details
• Public API -- Programmatic methods for configuration, escalation, and offline control. Details
• Branding -- Custom primary color, company name, and logo via config. Details

Documentation

1. Configuration -- All config options: socket, theme, user, branding, features, offline, post-chat
2. Pre-Chat Flow -- Step types, routing logic, FAQ-only mode
3. Theming -- CSS custom properties reference and built-in themes
4. Events -- CustomEvent reference with detail payloads
5. API Methods -- Public methods: configure(), escalate(), showOffline()

License

MIT