Provider Setup

The GuideKitProvider is the root component that initializes the SDK and provides context to all hooks.

Basic Usage


import { GuideKitProvider } from '@guidekit/react';
 
<GuideKitProvider
  tokenEndpoint="/api/guidekit/token"
  agent={{ name: 'Aria', greeting: 'Welcome!' }}
>
  {children}
</GuideKitProvider>

Props

Authentication

Prop	Type	Description
`tokenEndpoint`	`string`	URL of your token endpoint (recommended)
`stt`	`STTConfig`	Direct STT config (dev only)
`tts`	`TTSConfig`	Direct TTS config (dev only)
`llm`	`LLMConfig`	Direct LLM config (dev only)

Agent Configuration


agent={{
  name: 'Guide',                              // Agent's display name
  greeting: 'Hi! Want me to show you around?' // First-visit greeting
}}

Content Map

Prevents hallucination by providing factual content the LLM can reference:


// Static content map
<GuideKitProvider
  contentMap={{
    'section-pricing': {
      description: 'Pricing starts at $29/mo',
      facts: ['14-day free trial', 'No credit card required'],
    },
  }}
>
 
// Dynamic content map (supports async)
<GuideKitProvider
  contentMap={(sectionId) => {
    if (sectionId === 'section-inventory') {
      return { description: `${inventory.count} items in stock`, facts: [] };
    }
    return null;
  }}
>

Options


options={{
  locale: 'auto',             // Auto-detect from <html lang>
  mode: 'voice',              // 'voice' | 'text' | 'auto'
  greetOnFirstVisit: true,    // Visual greeting for new visitors
  spotlightColor: '#4a9eed',  // Spotlight highlight color
  debug: false,               // Enable debug logging
}}

Theme


theme={{
  primaryColor: '#4a9eed',
  borderRadius: '20px',
  position: 'bottom-right',
  zIndex: 1000, // default: 2147483647
}}

Callbacks


<GuideKitProvider
  onError={(err) => console.error(err)}
  onEvent={(event) => analytics.track(event.type, event.data)}
  onReady={() => console.log('GuideKit ready!')}
  onBeforeLLMCall={(ctx) => {
    // Privacy hook — modify or cancel LLM calls
    // ctx.systemPrompt, ctx.userMessage, ctx.conversationHistory
  }}
>

Advanced

Prop	Type	Default	Description
`instanceId`	`string`	`'default'`	For multi-instance setups
`rootElement`	`HTMLElement`	`document.body`	DOM scan scope
`locale`	`string \| object`	`'auto'`	i18n locale or custom strings

Provider Types

Authentication configs use discriminated unions for type safety:


type LLMConfig =
  | { provider: 'gemini'; apiKey: string; model?: 'gemini-2.5-flash' | 'gemini-2.5-pro' }
  | { adapter: LLMProviderAdapter };
 
type STTConfig =
  | { provider: 'deepgram'; apiKey: string; model?: 'nova-2' | 'nova-3' }
  | { provider: 'elevenlabs'; apiKey: string; language?: string }
  | { provider: 'web-speech'; language?: string; continuous?: boolean; interimResults?: boolean };
 
type TTSConfig =
  | { provider: 'elevenlabs'; apiKey: string; voiceId?: string }
  | { provider: 'web-speech'; voice?: string; rate?: number; pitch?: number; language?: string };

SSR Safety

The provider is fully SSR-safe:

No browser APIs are called during server-side rendering
Hooks return safe defaults (isReady: false, agentState: { status: 'idle' })
All initialization is deferred to client-side mounting
Compatible with Next.js App Router and Pages Router