React Native Widget

The Qafka component is a drop-in chat widget with full UI, theming, streaming, and voice support.

Basic Usage

import { Qafka } from '@qafka/react-native'
 
export default function ChatScreen() {
  return <Qafka />
}

The widget calls useSafeAreaInsets internally, so make sure a <SafeAreaProvider> exists somewhere above it in the tree (Expo Router, React Navigation, and most RN starter templates already include one).

Set up your project with the Qafka CLI (qafka init) so the widget can find the development key — see Quick Start.

Responses stream in real-time by default — tokens render in the message bubble as they arrive, with a typing indicator while the AI is thinking.

Display Modes

<Qafka mode="fullscreen" />

Props Reference

Event Callbacks

Imperative Handle

Pass a ref to control the widget programmatically:

import { useRef } from 'react'
import { Qafka, type QafkaHandle } from '@qafka/react-native'
 
const qafkaRef = useRef<QafkaHandle>(null)
 
<Qafka ref={qafkaRef} />
 
// Send a message as if the user typed it
qafkaRef.current?.sendMessage('Show my orders')
 
// Voice session control
await qafkaRef.current?.connectVoice()
await qafkaRef.current?.disconnectVoice()
qafkaRef.current?.pauseMic()
qafkaRef.current?.resumeMic()
 
// Voice loading pill (for async work outside onToolSuggested)
qafkaRef.current?.setLoading(true, 'Fetching data…')
qafkaRef.current?.setLoading(false)
 
// Reset voice tool cards
qafkaRef.current?.clearRenderedTools()

Customizing Components

The widget renders sensible defaults for every interactive surface, but you can swap any of them out for your own component to match your app’s visual language.

Header Buttons (Back / Close)

The back and close buttons appear in the header only when you wire up their callbacks. To replace the default rendering, pass BackComponent / CloseComponent:

<Qafka
  onBack={() => navigation.goBack()}
  onClose={() => navigation.navigate('Home')}
  BackComponent={() => <MyBackButton />}
  CloseComponent={() => <MyCloseButton />}
/>

Navigation Buttons

When the AI suggests a navigation target, the widget renders a button. Replace the rendering with NavigationButtonComponent, or just rewrite the label with navigationLabelFormat.

// Just change the label text
<Qafka navigationLabelFormat={(screen) => `Go to ${screen}`} />
 
// Replace the entire button
<Qafka
  NavigationButtonComponent={({ screenName, onPress, theme, label }) => (
    <TouchableOpacity onPress={onPress} style={myButtonStyle(theme)}>
      <Text>{label}</Text>
    </TouchableOpacity>
  )}
/>

The component receives { screenName, suggestion, onPress, theme, style, label, icon }.

Voice Page Components

The voice page has three slots — animation indicator, background container, and transcript text. Provide any subset; missing ones fall back to defaults.

import LottieView from 'lottie-react-native'
import voiceLottie from './voice-blob.json'
 
<Qafka
  voiceComponents={{
    VoiceIndicator: ({ state, amplitude, theme }) => (
      <LottieView
        source={voiceLottie}
        autoPlay
        loop
        speed={state === 'speaking' ? 1.5 : 1}
      />
    ),
    VoiceBackground: ({ state, children, theme }) => (
      <LinearGradient colors={['#1A1A2E', '#16213E']} style={{ flex: 1 }}>
        {children}
      </LinearGradient>
    ),
    VoiceTranscript: ({ transcript, userTranscript, state, theme }) => (
      <Text style={{ color: theme.colors.text }}>
        {state === 'listening' ? userTranscript : transcript}
      </Text>
    ),
  }}
/>

Each slot receives the live voice state ('idle' | 'connecting' | 'listening' | 'thinking' | 'speaking'), the current audio amplitude (0–1), and the active theme.

Tool Response Components

When a tool result comes back, the widget renders it with a default Card / List / Detail / Table component based on the tool’s response.type. Override these by registering your own components and referencing them by name from the dashboard’s tool config.

import { CampaignCard, ProductRow } from './chat-renderers'
 
<Qafka
  components={{
    CampaignCard,
    ProductRow,
  }}
/>

Each registered component receives { data, tool, theme, onAction }. In the dashboard, set the tool’s response.itemComponent to the matching key ("CampaignCard", "ProductRow") to use your renderer instead of the default.

Card CTAs

When a tool is configured to use the Card renderer in the dashboard (see Tools — UI Rendering), buttons inside the card fire one of seven action types. Five of them have built-in SDK behavior; two cross the SDK boundary and need a host callback.

SDK-internal actions (no setup needed)

Override any of these via onCardSuggestMessage, onCardCopy, onCardShare, onCardExternalNavigation if you want custom behavior (e.g. show a toast on copy).

Host-bound actions

deep_link — internal route navigation

Card author writes the path in the dashboard (with optional {{template}} placeholders that resolve at click time):

{
  "component": "QButton",
  "label": "Detayları Gör",
  "variant": "primary",
  "action": {
    "action": { "type": "deep_link", "path": "/store/{{id}}" }
  }
}

Partner registers the handler:

import { useRouter } from 'expo-router'
 
const router = useRouter()
 
<Qafka
  // ...other props
  onCardDeepLink={(path) => router.push(path)}
/>

When the partner doesn’t provide onCardDeepLink, the action is silently skipped and a dev-mode warning is logged.

tool_trigger — fire another tool from a card

For chains where one card spawns another (e.g. “Confirm booking” button calls a bookAppointment tool):

<Qafka
  onCardToolTrigger={(toolName, params, meta) => {
    sdk.invokeTool(toolName, params)
  }}
/>

meta.ctaDisplayMode is 'user_message' (default) or 'silent' — controls whether the trigger appears as a user bubble in chat history.

CTA telemetry

onCardCTAClick fires once per button press. Event shape:

{
  event: 'cta_click',
  cardTemplateId: string,
  cardSlug: string,
  actionType: 'external_navigation' | 'deep_link' | ...,
  toolName?: string,
  messageId?: string,
  itemIndex?: number,   // only set in list mode
  item: unknown,        // the bound record (item in list mode, full result in detail mode)
  confirmed: boolean,
}

item carries the actual record the partner is acting on, so you don’t need to keep the source array around to look it up by index. Forward it to your analytics service:

<Qafka
  onCardCTAClick={(event) => {
    analytics.track('card_cta_click', {
      action: event.actionType,
      template: event.cardTemplateId,
      itemId: (event.item as any)?.id,
    })
  }}
/>