React Component - ThunderPhone

The ThunderPhoneWidget component renders a glassmorphic call bar with built-in controls for muting, ending the call, and displaying connection status. It is the fastest way to add voice AI to a React app.

Installation

npm install @thunderphone/widget

Basic Usage

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
    />
  )
}

You must import the CSS file for the widget to render correctly. Without it, the widget will be unstyled.

Props

The component accepts the following props via ThunderPhoneWidgetProps:

Prop	Type	Required	Default	Description
`publishableKey`	`string`	Yes	—	Publishable API key (`pk_live_...`) from the Developers settings. The agent is resolved automatically from the key’s widget configuration.
`theme`	`'light' \| 'dark'`	No	`'light'`	Color scheme. Applies `tp--light` or `tp--dark` class to the widget root.
`primaryColor`	`string`	No	`'#000000'` (light) / `'#ffffff'` (dark)	CSS color string used as the accent color (call button, waveform, active indicators).
`title`	`string`	No	`'Voice assistant'`	Text displayed in the widget bar.
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	No	`'bottom-right'`	Fixed viewport position for the widget.
`apiBase`	`string`	No	`'https://api.thunderphone.com/v1'`	API base URL override.
`language`	`string`	No	—	Per-session language override — a language code or locale such as `en`, `es`, or `fr-FR`. When unset, the agent’s configured language applies.
`voice`	`string`	No	—	Per-session voice override — a voice name such as `maria`. When unset, the agent’s configured voice applies.
`context`	`string`	No	—	Per-session factual page or site context passed to the agent (for example, details of the page the visitor is viewing). Truncated server-side to 12,000 characters.
`onConnect`	`() => void`	No	—	Called when the voice session successfully connects.
`onDisconnect`	`() => void`	No	—	Called when the session ends.
`onError`	`(error) => void`	No	—	Called on errors. The `error` object has `error` (code) and `message` fields.
`className`	`string`	No	—	Additional CSS class name applied to the widget container.
`ringtone`	`boolean \| string`	No	`false`	Play a ringtone while connecting. `true` for the default ringtone, or a URL string for custom audio.

Examples

Dark Theme with Custom Color

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
      title="Talk to our AI"
    />
  )
}

Custom Position

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      position="bottom-left"
    />
  )
}

Per-Session Language, Voice, and Context

The language, voice, and context props are forwarded to the session request (POST /widget/session) when a call starts, overriding the agent’s configured defaults for that session:

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function PricingPageWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      language="es"
      voice="maria"
      context="Page: Pricing. Plans: Starter $29/mo, Pro $99/mo. Annual billing saves 20%."
    />
  )
}

Use context to give the agent factual knowledge about the page the visitor is on — product details, pricing, or page-specific FAQs. It is truncated server-side to 12,000 characters.

With Event Callbacks

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function SupportWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      onConnect={() => {
        console.log('Voice session connected')
        analytics.track('widget_call_started')
      }}
      onDisconnect={() => {
        console.log('Voice session ended')
        analytics.track('widget_call_ended')
      }}
      onError={(error) => {
        console.error(`Widget error: ${error.error} - ${error.message}`)
      }}
    />
  )
}

With Custom Styling

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function BrandedWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      primaryColor="#4a90d9"
      className="my-custom-widget"
    />
  )
}

.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}

See the Styling guide for all available CSS classes and custom properties.

With Ringtone

Play a phone-ringing sound while the connection is being established:

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function PhoneWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      ringtone={true}
    />
  )
}

Use a custom ringtone by passing an audio file URL:

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  ringtone="https://example.com/my-ringtone.mp3"
/>

The ringtone loops while the widget is in the connecting state and fades out smoothly when the agent connects.

With Custom API Base

You only need to set apiBase if you are using a self-hosted or proxy API endpoint. The default points to https://api.thunderphone.com/v1.

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  apiBase="https://your-proxy.example.com/v1"
/>

Error Handling

When the onError callback fires, it receives an error object with two fields:

Field	Type	Description
`error`	`string`	Machine-readable error code
`message`	`string`	Human-readable error description

Common error codes include domain not allowed, agent not found, and invalid API key.

Next Steps

Headless Hook

Need full control over the UI? Use the useThunderPhone hook instead.

Styling

Customize colors, sizes, and layout with CSS custom properties.

​Installation

​Basic Usage

​Props

​Examples

​Dark Theme with Custom Color

​Custom Position

​Per-Session Language, Voice, and Context

​With Event Callbacks

​With Custom Styling

​With Ringtone

​With Custom API Base

​Error Handling

​Next Steps

Headless Hook

Styling

Installation

Basic Usage

Props

Examples

Dark Theme with Custom Color

Custom Position

Per-Session Language, Voice, and Context

With Event Callbacks

With Custom Styling

With Ringtone

With Custom API Base

Error Handling

Next Steps