Widget Component

Learn how to use the LinguChat component in your React Native app.

Basic Usage

The simplest way to add chat to your app:

import React from 'react';
import { View } from 'react-native';
import { LinguChat } from '@lingu/react-native-sdk';

export default function App() {
  return (
    <View style={{ flex: 1 }}>
      {/* Your app content */}
      
      <LinguChat
        apiKey="your-api-key-here"
        position="bottom-right"
        theme="light"
        primaryColor="#4ade80"
      />
    </View>
  );
}

Props Reference

Required Props

Prop	Type	Description
apiKey	string	Your Lingu API key from the dashboard

Optional Props

Prop	Type	Default	Description
position	ChatPosition	bottom-right	Floating button position
theme	ThemeMode	light	Color theme
primaryColor	string	#4ade80	Primary accent color
autoOpen	boolean	false	Auto-open chat on mount
showBackButton	boolean	true	Show back button in header

Callback Props

Prop	Type	Description
onBackPress	() => void	Called when back button is pressed
onSessionStart	(sessionId: string) => void	Called when a new session starts
onSessionEnd	(sessionId: string) => void	Called when a session ends
onMessageSent	(message: string) => void	Called when user sends a message
onMessageReceived	(message: string) => void	Called when AI responds

Type Definitions

type ChatPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
type ThemeMode = 'light' | 'dark' | 'system';

Positioning

The position prop controls where the floating action button appears:

// Bottom right (default)
<LinguChat apiKey="..." position="bottom-right" />

// Bottom left
<LinguChat apiKey="..." position="bottom-left" />

TIP

When the chat opens, it takes up the full screen for the best mobile experience.

Theming

Light Theme (Default)

<LinguChat
  apiKey="your-api-key"
  theme="light"
  primaryColor="#3b82f6"  // Blue
/>

Dark Theme

<LinguChat
  apiKey="your-api-key"
  theme="dark"
  primaryColor="#4ade80"  // Green
/>

System Theme

Automatically follows the device's theme preference:

import { useColorScheme } from 'react-native';

function App() {
  const colorScheme = useColorScheme();
  
  return (
    <LinguChat
      apiKey="your-api-key"
      theme={colorScheme === 'dark' ? 'dark' : 'light'}
    />
  );
}

Event Callbacks

Track Session Events

<LinguChat
  apiKey="your-api-key"
  onSessionStart={(sessionId) => {
    console.log('Chat session started:', sessionId);
    analytics.track('chat_opened', { sessionId });
  }}
  onSessionEnd={(sessionId) => {
    console.log('Chat session ended:', sessionId);
    analytics.track('chat_closed', { sessionId });
  }}
/>

Track Messages

<LinguChat
  apiKey="your-api-key"
  onMessageSent={(message) => {
    console.log('User asked:', message);
    analytics.track('chat_message', { direction: 'sent', message });
  }}
  onMessageReceived={(message) => {
    console.log('AI replied:', message);
    analytics.track('chat_message', { direction: 'received', message });
  }}
/>

Handle Back Button

import { useNavigation } from '@react-navigation/native';

function ChatScreen() {
  const navigation = useNavigation();
  
  return (
    <LinguChat
      apiKey="your-api-key"
      showBackButton={true}
      onBackPress={() => {
        navigation.goBack();
      }}
    />
  );
}

Full Example

Here's a complete example with all common options:

import React from 'react';
import { View, Text, StyleSheet, useColorScheme } from 'react-native';
import { LinguChat } from '@lingu/react-native-sdk';

export default function App() {
  const colorScheme = useColorScheme();
  
  const handleSessionStart = (sessionId: string) => {
    console.log('Session started:', sessionId);
  };
  
  const handleSessionEnd = (sessionId: string) => {
    console.log('Session ended:', sessionId);
  };
  
  const handleMessageSent = (message: string) => {
    console.log('User:', message);
  };
  
  const handleMessageReceived = (message: string) => {
    console.log('Bot:', message);
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Welcome to My App</Text>
      
      <LinguChat
        apiKey="lingu_your_api_key_here"
        position="bottom-right"
        theme={colorScheme === 'dark' ? 'dark' : 'light'}
        primaryColor="#3b82f6"
        autoOpen={false}
        showBackButton={true}
        onSessionStart={handleSessionStart}
        onSessionEnd={handleSessionEnd}
        onMessageSent={handleMessageSent}
        onMessageReceived={handleMessageReceived}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    paddingTop: 50,
  },
  title: {
    fontSize: 24,
    fontWeight: 'bold',
  },
});

Best Practices

1. Place at Root Level: Add the component at your app's root or main layout
2. Single Instance: Only use one LinguChat instance at a time
3. Use Environment Variables: Store your API key securely
4. Handle Back Navigation: Provide a way for users to close the chat
5. Match Your Theme: Use colors that complement your app's design