Get started with a React frontend

Layercode makes it easy to build web-based voice agent applications in React. This guide walks you through a full-stack React example voice agent, letting users speak to a voice AI in their browser. Example code: layercodedev/example-frontend-react

This frontend example is designed for use with a backend. Check out our tutorials in Node.js and Python or for demo purposes, use the Layercode demo platform.

Setup

To get started, you’ll need a Layercode account and a voice agent. If you haven’t done so yet, follow our Getting Started Guide. Clone the example repo and install dependencies:

git clone https://github.com/layercodedev/example-frontend-react.git
cd example-frontend-react
npm install

Disable React Strict Mode for Development: React Strict Mode renders components twice in development, which causes the Layercode voice agent hook to initialize twice. This results in duplicate voice agent sessions and can cause issues like hearing the voice agent speak twice.If you’re using Create React App, remove <React.StrictMode> from your src/index.js or src/index.tsx:

src/index.tsx

import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import App from './App';

const root = ReactDOM.createRoot(
  document.getElementById('root') as HTMLElement
);
root.render(
  // Remove React.StrictMode wrapper for Layercode development
  <App />
);

If you’re using Vite, ensure React.StrictMode is not wrapping your app in src/main.tsx.

Project structure

This project uses Vite for fast React development, Tailwind CSS for styling, and TypeScript.

How it works

Connect to a Layercode voice agent

We use the React SDK useLayercodeAgent hook, which handles all the complexity required for real-time, low-latency, two-way voice agent interactions. Here’s a simplified example of how to use the React SDK in a React application:

import { useLayercodeAgent } from "@layercode/react-sdk";
import { AudioVisualization } from "./AudioVisualization";
import { ConnectionStatusIndicator } from "./ConnectionStatusIndicator";
import { MicrophoneIcon } from "../icons/MicrophoneIcon";

export default function VoiceAgent() {
  const { agentAudioAmplitude, status } = useLayercodeAgent({
    agentId: "your-agent-id",
    authorizeSessionEndpoint: "/api/authorize",
    onDataMessage: (data) => {
      console.log("Received data msg", data);
    },
  });

  return (
    <div className="w-96 h-96 border border-white rounded-lg flex flex-col gap-20 items-center justify-center">
      <h1 className="text-gray-800 text-xl font-bold">Voice Agent Demo</h1>
      <AudioVisualization amplitude={agentAudioAmplitude} height={75} />
      <div className="flex flex-col gap-4 items-center justify-center">
        <div className="h-12 px-4 rounded-full flex items-center gap-2 justify-center select-none bg-[#FF5B41]">
          <MicrophoneIcon />
        </div>
        <ConnectionStatusIndicator status={status} />
      </div>
    </div>
  );
}

import "./App.css";
import VoiceAgent from "./ui/VoiceAgent";

function App() {
  return (
    <div className="w-full min-h-[80vh] flex items-center justify-center">
      <VoiceAgent />
    </div>
  );
}

export default App;

The useLayercodeAgent hook accepts:

Your agent ID (from the Layercode Dashboard)
The endpoint to authorize the client session (see Authorize Client Session)
An optional callback function for handling data messages

On mount, the useLayercodeAgent hook will:

Make a request to your authorize session endpoint to create new session and return the client session key.
Establish a WebSocket connection to Layercode (using the client session key)
Capture microphone audio from the user and stream it to the Layercode voice agent for transcription
(At this stage, Layercode will call Your Backend webhook to generate a response, and then convert the response from text to speech)
Playback audio of the voice agent’s response to the user in their browser, as it’s generated

The useLayercodeAgent hook returns an object with the following properties:

status: The connection status of the voice agent. You can show this to the user to indicate the connection status.
agentAudioAmplitude: The amplitude of the audio from the voice agent. You can use this to drive an animation when the voice agent is speaking.

By default, your voice agent will handle turn taking in automatic mode. But you can configure your voice agent to use push to talk mode. If you are using push to talk mode see the push-to-talk instructions in the repo README and read about how the VoiceAgentPushToTalk component works below.

Components

AudioVisualization

The AudioVisualization component is used to visualize the audio from the voice agent. It uses the agentAudioAmplitude value returned from the useLayercodeAgent hook to drive the height of the audio bars with a simple animation.

src/ui/AudioVisualization.tsx

export function AudioVisualization({ amplitude, height = 46 }: { amplitude: number; height?: number }) {
  // Calculate the height of each bar based on amplitude
  const maxHeight = height;
  const minHeight = Math.floor(height / 6);
  const barWidth = Math.floor(minHeight);

  // Create multipliers for each bar to make middle bars taller
  const multipliers = [0.2, 0.5, 1.0, 0.5, 0.2];

  // Boost amplitude by 7 and ensure it's between 0 and 1
  const normalizedAmplitude = Math.min(Math.max(amplitude * 7, 0), 1);

  return (
    <div className="w-auto flex items-center gap-[2px]" style={{ height: `${height}px` }}>
      {multipliers.map((multiplier, index) => {
        const barHeight = minHeight + normalizedAmplitude * maxHeight * multiplier;

        return (
          <div
            key={index}
            className="flex flex-col items-center"
            style={{
              height: `${barHeight}px`,
              width: `${barWidth}px`,
            }}
          >
            {/* Top rounded cap */}
            <div
              className="bg-[#FF5B41] dark:bg-[#FF7B61] transition-all duration-20"
              style={{
                width: "100%",
                height: `${barWidth}px`,
                borderTopLeftRadius: "9999px",
                borderTopRightRadius: "9999px",
              }}
            />
            {/* Middle straight section */}
            <div
              className="bg-[#FF5B41] dark:bg-[#FF7B61] transition-all duration-20"
              style={{
                width: "100%",
                height: `calc(100% - ${2 * barWidth}px)`,
                borderRadius: 0,
              }}
            />
            {/* Bottom rounded cap */}
            <div
              className="bg-[#FF5B41] dark:bg-[#FF7B61] transition-all duration-20"
              style={{
                width: "100%",
                height: `${barWidth}px`,
                borderBottomLeftRadius: "9999px",
                borderBottomRightRadius: "9999px",
              }}
            />
          </div>
        );
      })}
    </div>
  );
}

ConnectionStatusIndicator

The ConnectionStatusIndicator component is used to display the connection status of the voice agent. It uses the status value returned from the useLayercodeAgent hook to display the connection status.

src/ui/ConnectionStatusIndicator.tsx

export function ConnectionStatusIndicator({ status }: { status: string }) {
  return (
    <div className="justify-self-start flex items-center gap-2 bg-white dark:bg-gray-800 sm:px-3 p-1 rounded-full shadow-sm dark:shadow-gray-900/30">
      <div className={`w-3 h-3 rounded-full ${status === "connected" ? "bg-green-500" : status === "connecting" ? "bg-yellow-500" : "bg-red-500"}`} />
      <span className="text-sm text-gray-700 dark:text-gray-300 hidden sm:block">
        {status === "connected" ? "Connected" : status === "connecting" ? "Connecting..." : status === "error" ? "Connection Error" : "Disconnected"}
      </span>
    </div>
  );
}

VoiceAgentPushToTalk (optional)

Because the useLayercodeAgent hook handles all of the audio streaming and playback, in most cases the microphone button is simply a visual aid and doesn’t implement any logic. A simple microphone icon inside a circle will suffice in most cases. Layercode does support ‘push-to-talk’ turn taking, as an alternative to automatic turn taking (read more about turn taking). When using ‘push-to-talk’ turn taking, holding down and releasing the MicrophoneButton must send a websocket message to tell Layercode the user has started and finished talking. In this example, we provide an alternative VoiceAgentPushToTalk component, that along with the MicrophoneButtonPushToTalk component, handles this logic. To use this mode, you’ll need to edit src/App.tsx to use the VoiceAgentPushToTalk component instead of the VoiceAgent component. Then in your Layercode Dashboard, you’ll need to click Edit in the Transcription section of your voice agent and set the Turn Taking to Push to Talk.

import { useLayercodeAgent } from '@layercode/react-sdk';
import { AudioVisualization } from './AudioVisualization';
import { ConnectionStatusIndicator } from './ConnectionStatusIndicator';
import { MicrophoneButtonPushToTalk } from './MicrophoneButtonPushToTalk';

export default function VoiceAgentPushToTalk() {
  const { agentAudioAmplitude, status, triggerUserTurnStarted, triggerUserTurnFinished } = useLayercodeAgent({
    agentId: "your-agent-id",
    authorizeSessionEndpoint: '/api/authorize',
    onDataMessage: (data) => {
      console.log('Received data msg', data);
    },
  });

return (

<div className="w-96 h-96 border border-white rounded-lg flex flex-col gap-20 items-center justify-center">
  <h1 className="text-gray-800 text-xl font-bold">Voice Agent Demo</h1>
  <AudioVisualization amplitude={agentAudioAmplitude} height={75} />
  <div className="flex flex-col gap-4 items-center justify-center">
    <MicrophoneButtonPushToTalk triggerUserTurnStarted={triggerUserTurnStarted} triggerUserTurnFinished={triggerUserTurnFinished} />
    <ConnectionStatusIndicator status={status} />
  </div>
</div>
); }

import { useButtonHold } from '../hooks/useButtonHold';
import { MicrophoneIcon } from '../icons/MicrophoneIcon';
export function MicrophoneButtonPushToTalk({ triggerUserTurnStarted, triggerUserTurnFinished }: { triggerUserTurnStarted: () => void; triggerUserTurnFinished: () => void }) {
  // When using push-to-talk turn taking in your Layercode voice agent, you'll need to call triggerUserTurnStarted and triggerUserTurnFinished when the user holds down the microphone button or spacebar.
  // The useButtonHold hook handles this state, and also includes debouncing so that short accidental clicks are ignored.
  const { isVisuallyPressed, handlePressStart, handlePressEnd } = useButtonHold({
    onPressStart: triggerUserTurnStarted,
    onPressEnd: triggerUserTurnFinished,
    key: 'Space',
  });

  return (
    <button
      className={`h-12 px-4 rounded-full flex items-center gap-2 justify-center cursor-pointer outline-none focus:outline-none transition-colors duration-200 select-none ${
        isVisuallyPressed ? 'bg-[#FF5B41]' : 'bg-gray-800 dark:bg-gray-700 hover:bg-black dark:hover:bg-gray-800'
      }`}
      onMouseDown={handlePressStart}
      onMouseUp={handlePressEnd}
      onMouseLeave={handlePressEnd}
      onTouchStart={handlePressStart}
      onTouchEnd={handlePressEnd}
    >
      <div className="text-sm font-medium text-white whitespace-nowrap">Hold while speaking</div>
      <MicrophoneIcon />
    </button>
  );
}

Overview

SDKs

How-to guides

Explanations

Get started with a React frontend

Setup

Project structure

How it works

Connect to a Layercode voice agent

Components

AudioVisualization

ConnectionStatusIndicator

VoiceAgentPushToTalk (optional)

​Setup

​Project structure

​How it works

​Connect to a Layercode voice agent

​Components

​AudioVisualization

​ConnectionStatusIndicator

​VoiceAgentPushToTalk (optional)

Setup

Project structure

How it works

Connect to a Layercode voice agent

Components

AudioVisualization

ConnectionStatusIndicator

VoiceAgentPushToTalk (optional)