qa-ai-widget

Drop-in AI Q&A floating widget for any web page. Users ask questions by voice or text, get answers from OpenAI, and hear them read aloud via ElevenLabs TTS.

Voice / Text  -->  POST /api/ask (OpenAI)  -->  POST /api/tts (ElevenLabs)  -->  Audio playback

Features:

• Voice input via Web Speech API (with real-time interim transcription)
• Text fallback for browsers without speech recognition
• Answers generated by OpenAI (any chat model)
• Text-to-speech via ElevenLabs (streaming MP3)
• Fully themeable — colors, fonts, sizes, position via CSS custom properties or JS
• i18n — built-in English and Polish, extensible
• Express Router on the backend — plug into any Express app
• Optional knowledge base file injected into the system prompt
• Zero dependencies on the client side

Quick start

1. Install

npm install qa-ai-widget

2. Server (Express)

import 'dotenv/config';
import express from 'express';
import path from 'node:path';
import { createQARouter } from 'qa-ai-widget/server';

const app = express();
app.use(express.json());

const qa = createQARouter({
  gameInfoPath: path.resolve('knowledge-base.md'), // optional
  systemPromptLines: [
    'You are a helpful assistant for our product.',
    'Answer in 2-3 sentences, natural spoken language.',
  ],
  model: 'gpt-4o',
});

app.use(qa);

// Serve the client files (if not using a bundler)
app.use('/qa', express.static('node_modules/qa-ai-widget'));

app.listen(3000);

3. Environment variables

OPENAI_API_KEY=sk-...
ELEVENLABS_API_KEY=sk_...
ELEVENLABS_VOICE_IDS=voice_id_1,voice_id_2

4. Client (HTML)

<link rel="stylesheet" href="/qa/qa-widget.css">
<script type="module">
  import { initQAWidget } from '/qa/client.js';
  initQAWidget({ lang: 'en', position: 'bottom-right' });
</script>

That's it — a floating mic button appears in the corner.

Client API

initQAWidget(options?)

Mount the widget and return the QAWidget instance. Safe to call multiple times (idempotent).

new QAWidget(options?)

Create and mount the widget manually.

| Option | Type | Default | Description | |---|---|---|---| | apiBase | string | '' | Base URL for /api/ask and /api/tts endpoints | | lang | string | 'en' | UI language ('en' or 'pl') | | speechLang | string | 'en-US' | Web Speech API language code (e.g. 'pl-PL', 'de-DE') | | position | string | 'bottom-right' | Widget position: 'bottom-right', 'bottom-left', 'top-right', 'top-left' | | container | Element | document.body | DOM element to mount into | | theme | object | null | Theme overrides (see Theming below) |

Instance methods

| Method | Description | |---|---| | expand() | Open the panel | | collapse() | Close the panel (stops audio & recognition) | | toggleListen() | Start/stop voice recognition | | askText(question) | Submit a text question programmatically | | stopSpeaking() | Stop audio playback | | replay() | Replay the last answer | | toggleTextMode() | Toggle the text input field | | destroy() | Remove the widget from the DOM and clean up |

Server API

createQARouter(options?)

Returns an Express Router with two endpoints:

• POST /api/ask — { question } → { answer }
• POST /api/tts — { text } → audio/mpeg stream

| Option | Type | Default | Description | |---|---|---|---| | gameInfoPath | string | — | Absolute path to a knowledge-base file (read on each request) | | systemPromptLines | string[] | Generic assistant prompt | Lines joined with \n to form the system prompt | | model | string | 'gpt-4o' | OpenAI chat model | | temperature | number | 0.6 | Sampling temperature | | maxTokens | number | 400 | Max response tokens | | ttsModel | string | 'eleven_multilingual_v2' | ElevenLabs model | | ttsVoiceSettings | object | { stability: 0.45, similarity_boost: 0.8 } | Voice settings |

The router also exposes router.getStatus() returning the current config state (useful for health checks).

Theming

Via CSS custom properties

Override any variable on #qa-widget or a parent selector:

#qa-widget {
  --qa-accent: #00bfff;
  --qa-secondary: #ff6b9d;
  --qa-bg: #1a1a2e;
  --qa-bg-2: #16162a;
  --qa-text: #f0f0f0;
  --qa-mono: "Fira Code", monospace;
  --qa-sans: "Inter", sans-serif;
  --qa-fab-size: 64px;
  --qa-panel-width: 500px;
  --qa-radius: 8px;
}

Via JS theme object

initQAWidget({
  theme: {
    accent: '#00bfff',
    secondary: '#ff6b9d',
    bg: '#1a1a2e',
    fontMono: '"Fira Code", monospace',
    fabSize: '64px',
    radius: '8px',
  },
});

All theme keys

| JS key | CSS variable | Default | Description | |---|---|---|---| | accent | --qa-accent | #4dff9a | Primary color (mic, speaking, idle) | | accentGlow | --qa-accent-glow | rgba(77,255,154,.35) | Accent glow / shadow | | secondary | --qa-secondary | #c66bff | Secondary color (thinking, answer) | | secondaryGlow | --qa-secondary-glow | rgba(198,107,255,.35) | Secondary glow | | error | --qa-error | #ff3d6e | Error / listening color | | waiting | --qa-waiting | #ffd24d | TTS loading color | | bg | --qa-bg | #11161c | Panel background | | bg2 | --qa-bg-2 | #0d1217 | Status bar / footer background | | border | --qa-border | #1d242c | Border color | | borderStrong | --qa-border-strong | #2b3540 | Strong border color | | text | --qa-text | #e8e8ec | Primary text color | | dim | --qa-dim | #6a7682 | Dimmed text | | dim2 | --qa-dim-2 | #8a96a3 | Secondary dimmed text | | fontMono | --qa-mono | "JetBrains Mono", monospace | Monospace font stack | | fontSans | --qa-sans | "Space Grotesk", sans-serif | Sans-serif font stack | | fabSize | --qa-fab-size | 72px | Floating button size | | panelWidth | --qa-panel-width | 600px | Panel width | | panelMaxHeight | --qa-panel-max-height | min(80vh, 760px) | Panel max height | | radius | --qa-radius | 4px | Border radius |

State machine

The widget cycles through these states, reflected as data-state on #qa-widget:

idle  -->  listening  -->  thinking  -->  synthesizing  -->  speaking  -->  idle
                |              |               |               |
                +--------------+---------------+---------------+--->  error  -->  idle

Each state has distinct visual indicators (colors, animations) driven by the CSS.

Browser support

• Voice input: Chrome, Edge (Web Speech API). Other browsers fall back to text-only mode automatically.
• Audio playback: All modern browsers.
• CSS color-mix(): Chrome 111+, Firefox 113+, Safari 16.2+.

License

MIT