tomevault-io Deploy Simba Chat Widget
npm: https://www.npmjs.com/package/simba-chat
Before You Start
Required: You need an Organization ID to use the widget. Fetch available organizations:
curl -s http://localhost:8000/api/v1/organizations | jq
If organizations are found, ask the user which one to use for the widget. If no organizations exist or the API is not running, instruct them to:
- Start the Simba API server (
make server) - Create an organization in the Simba dashboard
1-Minute Setup
npm install simba-chat
import { SimbaChatBubble } from 'simba-chat';
import 'simba-chat/styles.css';
// Add anywhere in your app
<SimbaChatBubble
apiUrl="http://localhost:8000" // Your Simba API
organizationId="your-org-id" // Required: Your organization ID
/>
Done! The chat widget appears in the bottom-right corner (default).
Configuration
| Prop | Type | Default | Description |
|---|---|---|---|
apiUrl |
string |
Required | Simba API URL |
organizationId |
string |
Required | Your organization ID |
position |
"bottom-left" | "bottom-right" |
"bottom-right" |
Widget position |
collection |
string |
"default" |
Knowledge base collection |
defaultOpen |
boolean |
false |
Start with chat open |
placeholder |
string |
"Type a message..." |
Input placeholder |
apiKey |
string |
- | For authenticated requests |
Framework Examples
Next.js
// app/layout.tsx
import { SimbaChatBubble } from 'simba-chat';
import 'simba-chat/styles.css';
export default function RootLayout({ children }) {
return (
<html>
<body>
{children}
<SimbaChatBubble
apiUrl="http://localhost:8000"
organizationId="your-org-id"
/>
</body>
</html>
);
}
React (Vite/CRA)
// main.tsx or App.tsx
import { SimbaChatBubble } from 'simba-chat';
import 'simba-chat/styles.css';
function App() {
return (
<>
<YourApp />
<SimbaChatBubble
apiUrl="http://localhost:8000"
organizationId="your-org-id"
/>
</>
);
}
Plain HTML (No Build Step)
<script type="module">
import { SimbaChatBubble } from 'https://esm.sh/simba-chat@0.1.0';
import { createRoot } from 'https://esm.sh/react-dom@19/client';
import { createElement } from 'https://esm.sh/react@19';
const root = document.createElement('div');
document.body.appendChild(root);
createRoot(root).render(
createElement(SimbaChatBubble, {
apiUrl: 'http://localhost:8000',
organizationId: 'your-org-id'
})
);
</script>
<link rel="stylesheet" href="https://esm.sh/simba-chat@0.1.0/styles.css">
Theming
Match your brand with CSS variables:
:root {
--simba-primary: #2563eb; /* Button/accent color */
--simba-primary-foreground: #fff; /* Text on buttons */
--simba-background: #ffffff; /* Chat background */
--simba-foreground: #0f172a; /* Text color */
--simba-muted: #f1f5f9; /* Secondary background */
--simba-border: #e2e8f0; /* Border color */
--simba-radius: 0.5rem; /* Corner radius */
}
Dark Mode
.dark {
--simba-primary: #3b82f6;
--simba-background: #1e293b;
--simba-foreground: #f8fafc;
--simba-muted: #334155;
--simba-border: #475569;
}
Inline Chat (Embedded)
For embedding in a page section instead of floating:
import { SimbaChat } from 'simba-chat';
import 'simba-chat/styles.css';
<div style={{ height: '500px' }}>
<SimbaChat
apiUrl="http://localhost:8000"
organizationId="your-org-id"
placeholder="Ask a question..."
/>
</div>
Custom UI with Hook
Build your own chat interface:
import { useSimbaChat } from 'simba-chat';
function CustomChat() {
const { messages, status, sendMessage, stop } = useSimbaChat({
apiUrl: 'http://localhost:8000',
organizationId: 'your-org-id',
});
return (
<div>
{messages.map((msg) => (
<div key={msg.id}>{msg.role}: {msg.content}</div>
))}
<input => {
if (e.key === 'Enter') sendMessage(e.target.value);
}} />
{status === 'streaming' && <button
</div>
);
}
Environment Variables
# .env.local
NEXT_PUBLIC_SIMBA_API_URL=http://localhost:8000
# .env.production
NEXT_PUBLIC_SIMBA_API_URL=https://api.simba.example.com
Troubleshooting
| Issue | Solution |
|---|---|
| Widget not showing | Check simba-chat/styles.css is imported |
| CORS errors | Add client domain to Simba API CORS config |
| No responses | Verify apiUrl and collection are correct |
Quick Checklist
-
npm install simba-chat - Import component and styles
- Set
apiUrlto your Simba API - Set
organizationId(required - get fromcurl http://localhost:8000/api/v1/organizations) - Optionally set
position="bottom-left"(default is bottom-right) - Customize colors with CSS variables
- Test on mobile
Converted and distributed by TomeVault — claim your Tome and manage your conversions.