@ariontalk/widget
@ariontalk/widget is a drop-in Web Component that wraps @ariontalk/core with a ready-made UI. It renders a floating action button, a live session panel, and an optional voice-settings panel — all encapsulated in Shadow DOM.
Installation
CDN
<script type="module" src="https://cdn.jsdelivr.net/npm/@ariontalk/widget@latest/dist/ariontalk.js" async></script>npm
pnpm add @ariontalk/widgetimport '@ariontalk/widget';Custom Element
<ariontalk-widget></ariontalk-widget>Attributes
All attributes are optional. Attribute names use kebab-case in HTML; the corresponding Lit property names are shown in parentheses where they differ.
| Attribute | Type | Default | Description |
|---|---|---|---|
site-key (siteKey) | string | '' | Site key for the ArionTalk cloud service. When set, engine resolves to 'gemini' and service-url is defaulted automatically. |
service-url (serviceUrl) | string | auto | Base URL for the ArionTalk cloud service. Defaulted automatically when site-key is present. |
lang | SupportedLang | 'auto' | Initial language. 'auto' reads the page’s <html lang> on the first session; otherwise pass a BCP-47 code like 'en', 'es', 'ja'. |
position | 'bottom-right' | 'bottom-left' | 'bottom-right' | Screen corner where the widget is anchored. Reflected to attribute. |
theme | 'light' | 'dark' | 'light' | Color theme. Reflected to attribute. Sets CSS custom property values on the host. |
label | string | 'Voice Chat' | Text shown on the floating action button. |
variant | 'default' | 'compact' | 'default' | FAB size variant. Reflected to attribute. |
icon | 'mic' | 'wave' | 'mic' | FAB icon. |
force | boolean | false | When set, skips the browser-support check and always renders the widget UI. |
settings | boolean | false | When set, shows a settings gear icon next to the FAB for pre-session voice configuration. |
barge-in-plugins (bargeInPlugins) | BargeInPlugin[] | [] | Array of barge-in plugin descriptors. Set via JavaScript property (not HTML attribute). |
log-level (logLevel) | LogLevel | 'disabled' | Console log verbosity: 'disabled', 'error', 'warning', 'info', or 'debug'. |
engine | 'local' | 'gemini' | 'local' | Engine type. 'local' uses browser-native APIs; 'gemini' uses the Gemini Live cloud API. Resolves to 'gemini' automatically when site-key is present and engine is not explicitly set. |
token-server (tokenServer) | string | '' | URL of a self-hosted token server. Kept for back-compat; prefer site-key + service-url for the ArionTalk cloud service. |
interactive-highlights (interactiveHighlights) | boolean | false | Enable real-time scroll-and-highlight during Gemini conversations. |
gemini-model (geminiModel) | string | '' | Gemini model identifier (e.g. 'gemini-3.1-flash-live-preview'). |
gemini-voice (geminiVoice) | string | '' | Gemini voice name for TTS output (e.g. 'Kore', 'Puck'). |
BargeInPlugin interface
Used when passing plugins via the bargeInPlugins property.
interface BargeInPlugin { /** Unique identifier, used for settings persistence. */ id: string; /** Display label shown in the settings UI. */ label: string; /** Optional tooltip describing the strategy. */ tooltip?: string; /** Factory function that creates a new detector instance. Called per session. */ create: () => BargeInDetector;}Events
All events bubble and are composed (cross Shadow DOM boundaries).
| Event | detail | Description |
|---|---|---|
at-session-start | { lang: string } | Fired when the user clicks the FAB and a voice session begins. |
at-session-end | { duration: number, messageCount: number } | Fired when the session ends. duration is elapsed seconds. |
const widget = document.querySelector('ariontalk-widget');
widget.addEventListener('at-session-start', (e) => { console.log('Session started, lang:', e.detail.lang);});
widget.addEventListener('at-session-end', (e) => { console.log('Session ended after', e.detail.duration, 'seconds');});CSS Custom Properties
All custom properties use the --at- prefix. Override them on the <ariontalk-widget> element or any ancestor to customize appearance.
| Property | Light Default | Dark Default | Description |
|---|---|---|---|
--at-primary-color | #111827 | #FAFAFA | Primary accent color (FAB background, focus rings). |
--at-primary-text | #FFFFFF | #18181B | Text color on primary backgrounds. |
--at-text-color | #1F2937 | #FAFAFA | Main body text color. |
--at-text-secondary | #6B7280 | #A1A1AA | Secondary / subtitle text. |
--at-text-muted | #9CA3AF | #71717A | Muted / placeholder text. |
--at-bg-color | #FFFFFF | #18181B | Panel background. |
--at-surface-color | #F3F4F6 | #27272A | Raised-surface background (buttons, cards). |
--at-surface-hover | #E5E7EB | #3F3F46 | Surface hover state. |
--at-border-color | #D1D5DB | #3F3F46 | Border and divider color. |
--at-border-radius | 16px | 16px | Global border radius for panels. |
--at-font-family | system-ui, sans-serif | system-ui, sans-serif | Font stack. |
--at-shadow-color | rgba(0, 0, 0, 0.12) | rgba(0, 0, 0, 0.4) | Box-shadow color. |
--at-shadow-hover | rgba(0, 0, 0, 0.18) | rgba(0, 0, 0, 0.5) | Hover-state shadow color. |
--at-focus-ring | rgba(17, 24, 39, 0.2) | rgba(250, 250, 250, 0.25) | Focus ring color. |
--at-success-color | #10B981 | #34D399 | Success indicator (e.g. active listening). |
--at-error-color | #EF4444 | #F87171 | Error indicator and end-session button. |
--at-error-hover | #DC2626 | #EF4444 | End-session button hover state. |
Example override:
ariontalk-widget { --at-primary-color: #6366F1; --at-border-radius: 12px;}Minimize state
The active session can be collapsed to a compact indicator without ending it. Clicking the minimize button (visible whenever the session panel is open) swaps the expanded panel for <vcw-minimized>, which shows a status-aware icon:
- Listening — animated microphone.
- Speaking — animated waveform.
- Muted — muted microphone with an overlay indicator.
Clicking the minimized indicator re-expands the full session panel. The underlying voice engine, transcript, and timer continue running throughout.
Component Architecture
The widget is built from a hierarchy of Lit Web Components:
| Component | Element | Role |
|---|---|---|
ArionTalk | <ariontalk-widget> | Root shell. Manages lifecycle, settings persistence, theme, and engine selection. |
WidgetFab | <vcw-fab> | Floating action button shown in idle state. |
WidgetSession | <vcw-session> | Active session panel with status indicator, timer, transcript, mute, and minimize/end controls. |
WidgetMinimized | <vcw-minimized> | Collapsed indicator shown when the user minimizes an active session. |
WidgetVoiceSettings | <vcw-voice-settings> | Pre-session settings panel for language, voice, rate, pitch, volume, and barge-in plugin selection. |
VoiceSessionController
A Lit Reactive Controller that bridges the widget UI and the voice engine. It holds the active VoiceEngineInterface instance, delegates startSession / endSession / setMuted / switchLanguage / applyVoiceSettings calls, and triggers host.requestUpdate() on every state change. It also dynamically imports @ariontalk/engine-gemini when the Gemini engine is selected.
localStorage Schema
The widget persists user preferences under the key ariontalk:settings.
interface SavedSettings { lang: SupportedLang; // Selected language code voiceId: string; // Selected voice identifier (voiceURI or Gemini voice name) rate: number; // Speech rate multiplier (default 1.0) pitch: number; // Speech pitch multiplier (default 1.0) volume: number; // Speech volume 0–1 (default 1.0) bargeInPluginId: string; // Active barge-in plugin id, or 'off'}Settings are loaded on connectedCallback and saved whenever the user applies changes via the settings panel. If localStorage is unavailable or the stored JSON is corrupt, defaults are used silently.