Widget Template

The Widget template provides a compact, embeddable widget interface for Pipecat applications. It features a toggle button to show/hide the widget panel, which includes text input and audio controls.

import { WidgetTemplate } from "@pipecat-ai/voice-ui-kit";

<div className="fixed bottom-4 right-4">
  <WidgetTemplate
    connectParams={{
      webrtcUrl: "/api/offer"
    }}
  />
</div>

Overview

The Widget template is designed for embedding Pipecat functionality into existing applications. It provides:

Toggle Button: Show/hide the widget panel
Text Input: Message input with debounced sending
Audio Control: User audio input control
Auto-connect: Automatically connects on mount
Compact Design: Minimal footprint for embedding

Usage

Basic Usage

import { WidgetTemplate } from "@pipecat-ai/voice-ui-kit";

export default function App() {
  return (
    <div className="fixed bottom-4 right-4">
      <WidgetTemplate
        connectParams={{
          webrtcUrl: "/api/offer"
        }}
      />
    </div>
  );
}

Custom Toggle Label

<WidgetTemplate
  toggleButtonLabel="Chat with AI"
  connectParams={{
    webrtcUrl: "/api/offer"
  }}
/>

Custom Debounce Time

<WidgetTemplate
  debounceTime={500}
  connectParams={{
    webrtcUrl: "/api/offer"
  }}
/>

Custom Styling

<WidgetTemplate
  classNames={{
    container: "fixed bottom-4 right-4",
    toggleContainer: "bg-primary",
    toggleButton: "text-white",
    widgetContainer: "max-w-sm"
  }}
  connectParams={{
    webrtcUrl: "/api/offer"
  }}
/>

Props

Prop	Type	Default
`serverUrl?`	`string`	`undefined`
`debounceTime?`	`number`	`300`
`toggleButtonLabel?`	`string`	`"Open"`
`classNames?`	`{ container?: string; toggleContainer?: string; toggleButton?: string; widgetContainer?: string; }`	`{}`
`connectParams?`	`TransportConnectionParams`	`{}`

Toggle State

Closed: Shows toggle button with label (default: "Open")
Open: Shows toggle button as icon (chevron down) and displays widget panel

Text Input

The text input:

Automatically sends messages after debounce time (default: 300ms)
Is disabled when not connected or while sending
Shows loading state on send button while sending
Clears input after sending

Auto-connect

The widget automatically:

Connects on mount (connectOnMount={true})
Uses SmallWebRTC transport by default
Disables theme provider (uses parent theme)

When open, the widget panel displays:

Text Input: Message input with send button
Divider: Visual separator
User Audio Control: Audio input control with device selection

Integration

The Widget template:

Wraps content with PipecatAppBase for client setup
Uses noThemeProvider to inherit parent theme
Automatically connects on mount
Uses SmallWebRTC transport by default
Handles connection state and errors

Positioning

The widget is designed to be positioned using CSS. Common patterns:

Fixed Bottom Right

<div className="fixed bottom-4 right-4">
  <WidgetTemplate connectParams={...} />
</div>

Fixed Bottom Left

<div className="fixed bottom-4 left-4">
  <WidgetTemplate connectParams={...} />
</div>

Absolute Positioning

<div className="relative">
  <div className="absolute bottom-0 right-0">
    <WidgetTemplate connectParams={...} />
  </div>
</div>

Customization Example

import { WidgetTemplate } from "@pipecat-ai/voice-ui-kit";

export default function EmbeddedWidget() {
  return (
    <div className="fixed bottom-6 right-6 z-50">
      <WidgetTemplate
        toggleButtonLabel="Need Help?"
        debounceTime={500}
        classNames={{
          container: "flex flex-col gap-2",
          toggleContainer: "bg-blue-600 hover:bg-blue-700",
          toggleButton: "text-white font-semibold",
          widgetContainer: "bg-white dark:bg-gray-800"
        }}
        connectParams={{
          webrtcUrl: "/api/voice-assistant"
        }}
      />
    </div>
  );
}