@cuekit-ai/react

A powerful React SDK for integrating AI-powered voice interactions into your web applications. Built with TypeScript and designed for seamless voice navigation, commands, and interactions with WebRTC support for real-time voice communication.

🚀 Features

• 🎤 Real-time Voice Recognition: High-accuracy, real-time speech-to-text powered by WebRTC.
• 🤖 AI-Powered Navigation: Intelligent voice commands for seamless app navigation.
• 🎯 Intent Recognition: Understands user intent to perform actions on your site.
• 🎨 Modern UI: A beautiful, animated, and customizable voice assistant interface.
• 🌙 Theme Support: Automatic light/dark theme detection, with the ability to override.
• ✍️ Text Input: A built-in chat interface for text-based commands.
• 🔧 Customizable: Easily customize the look and feel to match your brand.

📦 Installation

npm install @cuekit-ai/react

After installation, you need to import the CSS file for styling:

// In your main CSS file or a root component
import '@cuekit-ai/react/styles.css'

🎯 Quick Start

Get up and running with CueKit in just two steps.

1. Wrap Your App with CuekitProvider

The CuekitProvider initializes the SDK and provides the necessary context to all child components. You should wrap your application's root component with it.

// Example for a React Router v6 application
import { CuekitProvider } from '@cuekit-ai/react'
import { useNavigate } from 'react-router-dom'

function App() {
  const navigate = useNavigate()

  const handleNavigation = (path, params) => {
    navigate(path, { state: params })
  }

  return (
    <CuekitProvider apiKey="YOUR_API_KEY" appId="YOUR_APP_ID" navigationHandler={handleNavigation}>
      {/* Your application components */}
    </CuekitProvider>
  )
}

2. Add the MicButton

The MicButton is the main UI component for the voice assistant. It can be placed anywhere in your application, but it's best to place it in a layout component that's always visible.

import { MicButton } from '@cuekit-ai/react'

function Layout({ children }) {
  return (
    <div>
      {children}
      <MicButton screenPosition="bottom-right" />
    </div>
  )
}

API Reference

CuekitProvider

The main provider component that enables all CueKit functionality.

| Prop | Type | Required | Description | | ------------------------- | ------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------- | | apiKey | string | ✅ | Your CueKit API key. | | appId | string | ✅ | Your application ID. | | navigationHandler | (path: string, params?: Record<string, any>) => void | ❌ | A function to handle navigation events. See Routing Integration for more details. | | onConnectionStateChange | (state: ConnectionState) => void | ❌ | A callback for WebRTC connection state changes. | | onParticipantUpdate | (participants: string[]) => void | ❌ | A callback for when the list of participants in the room changes. | | children | ReactNode | ✅ | Your app components. |

MicButton

The main UI component for the voice assistant.

| Prop | Type | Default | Description | | ---------------- | ---------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------ | | screenPosition | 'bottom-left' \| 'bottom-center' \| 'bottom-right' | 'bottom-right' | The position of the mic button on the screen. | | bottomSpace | number | 20 | The distance of the button from the bottom of the screen, in pixels. | | buttonSize | number | 52 | The size of the button, in pixels. | | defaultTheme | 'light' \| 'dark' \| 'system' | 'system' | The default theme for the chat popup. 'system' will auto-detect the user's system theme. | | buttonStyle | React.CSSProperties | {} | Custom styles for the button. | | imageSource | string | undefined | An image to display in the button instead of the default icon. | | imageStyle | React.CSSProperties | {} | Custom styles for the image. | | showBorderGlow | boolean | false | Whether to show an animated border glow around the button during active states. |

useCuekit Hook

The useCuekit hook is the primary way to interact with the CueKit SDK. It provides all the necessary state and functions to build a custom voice experience.

import { useCuekit } from '@cuekit-ai/react'

function CustomVoiceComponent() {
  const {
    isConnected,
    isConnecting,
    error,
    connect,
    disconnect,
    sendUserCommand,
    messages,
    micState,
    status,
  } = useCuekit()

  // Your custom UI and logic here
}

Return Values:

| Property | Type | Description | | ----------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------- | | isConnected | boolean | Whether the SDK is currently connected to the CueKit backend. | | isConnecting | boolean | Whether the SDK is currently attempting to connect. | | error | string \| null | Any error that occurred during connection or operation. | | connect | (identity: string, apiKey?: string, appId?: string) => Promise<void> | A function to connect to the CueKit backend. | | disconnect | () => Promise<void> | A function to disconnect from the CueKit backend. | | sendUserCommand | (command: string) => Promise<void> | A function to send a text command to the CueKit backend. | | messages | ChatMessage[] | An array of chat messages. | | micState | 'idle' \| 'listening' \| 'thinking' \| 'replying' | The current state of the microphone. | | status | string | A user-friendly status message. |

🎨 Styling

The SDK is styled with CSS variables, which makes it easy to customize the look and feel of the components.

CSS Variables

You can override the default values of these variables in your own CSS to match your brand.

/* Light theme (default) */
:root {
  --voice-bg: 0 0% 100%;
  --voice-surface: 0 0% 100%;
  --voice-border: 214.3 31.8% 91.4%;
  --voice-text: 222.2 84% 4.9%;
  --voice-text-muted: 215.4 16.3% 46.9%;
  --voice-accent: 200 98% 39%;
  --voice-accent-light: 200 98% 95%;
  --voice-user-bubble: 200 98% 39%;
  --voice-user-text: 0 0% 100%;
  --voice-ai-bubble: 0 0% 95%;
  --voice-ai-text: 222.2 84% 4.9%;
}

/* Dark theme */
.cuekit-dark {
  --voice-bg: 211 32% 11%;
  --voice-surface: 217.2 32.6% 17.5%;
  --voice-border: 217.2 32.6% 17.5%;
  --voice-text: 210 40% 98%;
  --voice-text-muted: 215 20.2% 65.1%;
  --voice-accent: 200 98% 60%;
  --voice-accent-light: 200 98% 20%;
  --voice-user-bubble: 200.12 80.39% 60%;
  --voice-user-text: 0 0% 100%;
  --voice-ai-bubble: 200.57 32.71% 20.98%;
  --voice-ai-text: 0 0% 100%;
}

Routing Integration

The SDK can integrate with your application's router via the navigationHandler prop on the CuekitProvider.

React Router v6 Example:

import { useNavigate } from 'react-router-dom'
import { CuekitProvider } from '@cuekit-ai/react'
import '@cuekit-ai/react/styles.css'

function AppProviders({ children }) {
  const navigate = useNavigate()

  return (
    <CuekitProvider
      apiKey="YOUR_API_KEY"
      appId="YOUR_APP_ID"
      navigationHandler={(path, params) => {
        navigate(path, { state: params })
      }}
    >
      {children}
    </CuekitProvider>
  )
}

Next.js Example:

'use client'

import { CuekitProvider } from '@cuekit-ai/react'
import { useRouter } from 'next/navigation'
import dynamic from 'next/dynamic'
import React from 'react'
import '@cuekit-ai/react/styles.css'

const DynamicCuekitProvider = dynamic(
  () => import('@/providers/cuekit-provider').then((mod) => mod.CuekitProvider),
  {
    ssr: false,
  }
)

export default function AppProviders({ children }: { children: React.ReactNode }) {
  const router = useRouter()
  return (
    <DynamicCuekitProvider
      apiKey="YOUR_API_KEY"
      appId="YOUR_APP_ID"
      navigationHandler={(path, params) => {
        const qs = params ? `?${new URLSearchParams(params).toString()}` : ''
        router.push(`${path}${qs}`)
      }}
    >
      {children}
    </DynamicCuekitProvider>
  )
}

🐛 Troubleshooting

If you're having trouble, here are a few things to check:

• Microphone Not Working: Ensure that you've granted microphone permissions to your site. Also, the SDK requires a secure (HTTPS) connection to function.
• Voice Commands Not Recognized: Check your internet connection and ensure that you've provided a valid API key and app ID to the CuekitProvider.
• Styling Issues: Make sure you've imported the CSS file as described in the Installation section.

Made with ❤️ by CueKit