Pipecat App Base

The PipecatAppBase component reduces the boilerplate code required to bootstrap a new Pipecat Client application.

It handles the common setup tasks that are typically the same across most applications, providing a simpler developer experience:

Creates a Pipecat Client instance and manages its lifecycle.
Wraps children with the necessary providers (such as ThemeProvider and PipecatClientProvider).
Provides connect and disconnect handlers (sync or async).
Mounts the bot audio track via <BotAudioOutput />, which also binds playback volume to useBotAudioOutput.
Passes through transport and client options from the constructor.
Automatically disconnects and disposes the client when unmounting.
Surfaces error states to the child components.
Optionally disables theme provider based on noThemeProvider prop.
Optionally disables audio output for the bot based on noAudioOutput prop.

This component creates the PipecatClientProvider context for you. Child components will be able to use all Pipecat Client SDK hooks and components.

Usage

Parent / adjacent state changes will trigger component re-renders, which will recycle the Pipecat client instance. We recommend using this component at the highest order in your application, and not nesting it inside other components.

The PipecatAppBase component can be used in two ways:

1. Render Prop Pattern (Function Children)

This pattern gives you access to the client instance, connection handlers and state, allowing you to build custom UI that have direct access to these props:

import {
  PipecatAppBase,
  ErrorCard,
  SpinLoader,
} from "@pipecat-ai/voice-ui-kit";

export default function Home() {
  return (
    <PipecatAppBase
      transportType="smallwebrtc"
      connectParams={{
        webrtcUrl: "/api/offer",
      }}
    >
      {({ client, handleConnect, handleDisconnect, error }) =>
        !client ? (
          <SpinLoader />
        ) : error ? (
          <ErrorCard error={error} />
        ) : (
          <div>
            <button onClick={handleConnect}>Connect</button>
            <button onClick={handleDisconnect}>Disconnect</button>
          </div>
        )
      }
    </PipecatAppBase>
  );
}

2. Direct Children Pattern

This pattern is simpler when you want to use the built-in components that already handle connection state internally (e.g. using Pipecat React hooks).

import {
  PipecatAppBase,
  ConnectButton,
  ControlBar,
  UserAudioControl,
} from "@pipecat-ai/voice-ui-kit";

export default function Home() {
  return (
    <PipecatAppBase
      transportType="smallwebrtc"
      connectParams={{
        webrtcUrl: "/api/offer",
      }}
    >
      <div>
        <ConnectButton />
        <ControlBar>
          <UserAudioControl />
        </ControlBar>
      </div>
    </PipecatAppBase>
  );
}

3. Without Theme Provider

You can disable the theme provider wrapper by setting noThemeProvider={true}:

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

export default function Home() {
  return (
    <PipecatAppBase
      transportType="smallwebrtc"
      connectParams={{
        webrtcUrl: "/api/offer",
      }}
      noThemeProvider={true}
    >
      <YourCustomComponent />
    </PipecatAppBase>
  );
}

4. Auto-Connect on Mount

You can automatically connect to the session when the component mounts by setting connectOnMount={true}:

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

export default function Home() {
  return (
    <PipecatAppBase
      transportType="smallwebrtc"
      connectParams={{
        webrtcUrl: "/api/offer",
      }}
      connectOnMount={true}
    >
      <YourCustomComponent />
    </PipecatAppBase>
  );
}

5. Initialize Devices on Mount

You can automatically initialize devices (microphone, camera, speakers) when the component mounts by setting initDevicesOnMount={true}:

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

export default function Home() {
  return (
    <PipecatAppBase
      transportType="smallwebrtc"
      connectParams={{
        webrtcUrl: "/api/offer",
      }}
      initDevicesOnMount={true}
    >
      <YourCustomComponent />
    </PipecatAppBase>
  );
}

6. Disable Audio Output

You can disable audio output for the bot by setting noAudioOutput={true}:

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

export default function Home() {
  return (
    <PipecatAppBase
      transportType="smallwebrtc"
      connectParams={{
        webrtcUrl: "/api/offer",
      }}
      noAudioOutput={true}
    >
      <YourCustomComponent />
    </PipecatAppBase>
  );
}

7. Using WebSocket Transport

The websocket transport is provided by an optional peer package that must be installed alongside the kit.

The WebSocket transport package is a peer dependency. Install it before setting transportType="websocket", otherwise the transport will fail to load at runtime.

npm install @pipecat-ai/websocket-transport

Then point the component at a startBot endpoint that returns WebSocket connection details:

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

export default function Home() {
  return (
    <PipecatAppBase
      transportType="websocket"
      startBotParams={{
        endpoint: "/api/start",
        requestData: {
          transport: "websocket",
        },
      }}
    >
      <YourCustomComponent />
    </PipecatAppBase>
  );
}

Transport-specific construction options can be passed via transportOptions, which is typed as WebSocketTransportConstructorOptions when transportType="websocket". See the @pipecat-ai/websocket-transport package for the full option list.

8. Using onClient Callback

onClient fires once per client instance, the moment the client is created and before any connect attempt. It's the right place to attach client.on(...) listeners or to run setup that needs the client handle from outside the provider tree (e.g. when consuming ConsoleTemplate, where there is no render-prop slot to call usePipecatClient() from).

It fires again each time the client is recreated, for example when transportType, transportOptions, or clientOptions change. Treat each call as a fresh subscription point.

import { PipecatAppBase } from "@pipecat-ai/voice-ui-kit";
import { type PipecatClient, RTVIEvent } from "@pipecat-ai/client-js";

export default function Home() {
  const handleClient = (client: PipecatClient) => {
    client.on(RTVIEvent.BotStartedSpeaking, () => {
      console.log("Bot started speaking");
    });
    client.on(RTVIEvent.UserStartedSpeaking, () => {
      console.log("User started speaking");
    });
  };

  return (
    <PipecatAppBase
      transportType="smallwebrtc"
      connectParams={{
        webrtcUrl: "/api/offer",
      }}
      onClient={handleClient}
    >
      <YourCustomComponent />
    </PipecatAppBase>
  );
}

A common use case is bootstrapping a transport-specific handshake on connect. For example, sending Twilio's expected connected and start messages immediately after the WebSocket transport opens:

import { PipecatAppBase } from "@pipecat-ai/voice-ui-kit";
import { type PipecatClient, RTVIEvent } from "@pipecat-ai/client-js";
import { type WebSocketTransport } from "@pipecat-ai/websocket-transport";

const handleClient = (client: PipecatClient) => {
  client.on(RTVIEvent.Connected, () => {
    const transport = client.transport as WebSocketTransport;
    void transport.sendRawMessage({
      event: "connected",
      protocol: "Call",
      version: "1.0.0",
    });
    void transport.sendRawMessage({
      event: "start",
      start: { streamSid: "mock", callSid: "mock" },
    });
  });
};

9. Using startBotParams

You can use startBotParams instead of connectParams to start a bot session:

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

export default function Home() {
  return (
    <PipecatAppBase
      transportType="smallwebrtc"
      startBotParams={{
        // Your startBot parameters
      }}
    >
      <YourCustomComponent />
    </PipecatAppBase>
  );
}

Props

Prop	Type	Default
`connectParams?`	`TransportConnectionParams`	-
`startBotParams?`	`APIRequest`	-
`startBotResponseTransformer?`	`(response: TransportConnectionParams) => TransportConnectionParams \| Promise<TransportConnectionParams>`	-
`transportType`	`"smallwebrtc" \| "daily" \| "websocket"`	-
`transportOptions?`	`SmallWebRTCTransportConstructorOptions \| DailyTransportConstructorOptions \| WebSocketTransportConstructorOptions`	-
`clientOptions?`	`Partial<PipecatClientOptions>`	-
`noThemeProvider?`	`boolean`	`false`
`themeProps?`	`Partial<ThemeProviderProps>`	-
`connectOnMount?`	`boolean`	`false`
`initDevicesOnMount?`	`boolean`	`false`
`noAudioOutput?`	`boolean`	`false`
`onClient?`	`(client: PipecatClient) => void`	-
`children`	`((props: PipecatBaseChildProps) => React.ReactNode) \| React.ReactNode`	-

Child Props

The PipecatAppBase component passes the following props to its children when using the render prop pattern:

Prop	Type	Default
`client`	`PipecatClient \| null`	-
`handleConnect?`	`() => void \| Promise<void>`	-
`handleDisconnect?`	`() => void \| Promise<void>`	-
`error?`	`string \| null`	-
`rawStartBotResponse?`	`TransportConnectionParams \| unknown`	-
`transformedStartBotResponse?`	`TransportConnectionParams \| unknown`	-

Changelog

v0.11.02026-05-11: Added websocket transport type support
Added onClient prop for subscribing to client events before connection
v0.10.02026-04-30: No longer wraps children with ConversationProvider. Conversation state is now provided by PipecatClientProvider from @pipecat-ai/client-react.
v0.8.22026-03-31: Use startBotAndConnect when connectParams is an APIRequest.
v0.5.02025-11-07: Added initDevicesOnMount prop, giving control over when device-access permissions are requested.
v0.4.02025-10-02: Updated for the latest Pipecat Client API.
v0.3.02025-09-17: Fixed memoization regressions.
Now accepts a partial clientOptions object.
v0.2.02025-08-16: Renamed from AudioClientHelper.
Now accepts both React node children and a render-prop list for prop injection.
Added noThemeProvider prop to disable the wrapping ThemeProvider.
Connection handlers handleConnect and handleDisconnect now accept sync or async functions.
Returns the client object via child props.
Fixed TypeScript component type to resolve JSX usage errors.

Changelog

On this page