@franklinhelp/sdk-react
v0.1.0-alpha.6
Published
Embeddable AI-native help center for modern SaaS applications
Downloads
5
Maintainers
theodenanyohReadme
@franklinhelp/sdk-react
Embeddable AI-powered help center sidebar for React applications.
Installation
Alpha Release
npm install @franklinhelp/sdk-react@alpha
# or
pnpm add @franklinhelp/sdk-react@alpha
# or
yarn add @franklinhelp/sdk-react@alphaNote: This is an alpha release. The API may change in future versions.
Quick Start
1. Import the component and styles
import { FranklinHelpCenter, useFranklin } from "@franklinhelp/sdk-react";
import "@franklinhelp/sdk-react/styles";2. Add the component to your app
function App() {
const franklin = useFranklin();
return (
<div id="app-root">
<YourApp />
<FranklinHelpCenter
ref={franklin.ref}
orgId={process.env.NEXT_PUBLIC_FRANKLIN_ORG_ID}
sdkKey={process.env.NEXT_PUBLIC_FRANKLIN_SDK_KEY}
shiftTargetSelector="#app-root"
defaultTab="ai"
theme={{
accent: "#3B82F6",
mode: "light"
}}
onOpen={() => console.log("Franklin opened")}
onClose={() => console.log("Franklin closed")}
/>
</div>
);
}3. Control the sidebar programmatically
// Open the sidebar
franklin.open();
// Close the sidebar
franklin.close();
// Toggle the sidebar
franklin.toggle();
// Push context to Franklin
franklin.pushContext({
route: window.location.pathname,
userId: user.id,
metadata: {
plan: "enterprise",
role: "admin"
}
});
// Switch the active tab before opening
franklin.setTab("knowledge");
franklin.open();Props
FranklinHelpCenterProps
| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| orgId | string | ✅ | - | Your Franklin organization ID |
| sdkKey | string | ✅ | - | Your Franklin SDK key |
| shiftTargetSelector | string | ❌ | - | CSS selector for the element to shift when sidebar opens |
| defaultTab | "ai" \| "knowledge" \| "cases" | ❌ | "ai" | Default tab to show when sidebar opens |
| theme | FranklinThemeConfig | ❌ | {} | Theme customization options |
| onOpen | () => void | ❌ | - | Callback when sidebar opens |
| onClose | () => void | ❌ | - | Callback when sidebar closes |
| apiEndpoint | string | ❌ | "/api/franklin" | API endpoint for Franklin backend |
FranklinThemeConfig
interface FranklinThemeConfig {
mode?: "light" | "dark" | "auto";
accent?: string;
surface?: string;
border?: string;
radius?: number;
fontFamily?: string;
}Hooks
useFranklin()
Returns imperative controls for the Franklin sidebar:
const franklin = useFranklin();
franklin.open(); // Open sidebar
franklin.close(); // Close sidebar
franklin.toggle(); // Toggle sidebar
franklin.pushContext({ /* context */ }); // Update context
franklin.setTab("knowledge"); // Choose active tab
franklin.isOpen; // Current open state
franklin.activeTab; // Current active tabuseFranklinContext()
Access the Franklin context directly (must be used within FranklinProvider):
const {
isOpen,
activeTab,
context,
theme,
orgId,
sdkKey
} = useFranklinContext();Features
AI Chat
- Powered by Vercel AI SDK
- Real-time streaming responses
- Quick action suggestions
- Context-aware answers
Knowledge Base
- Browse articles by category
- Search functionality
- Article detail view
- Markdown content support
Cases Management
- View open support cases
- Case status tracking
- Message history
- Priority indicators
Customization
Theme
<FranklinHelpCenter
theme={{
mode: "dark",
accent: "#7C3AED",
radius: 12,
fontFamily: "'Inter', sans-serif"
}}
/>Setting
theme.modeto"light"or"dark"toggles adata-franklin-themeattribute on the host<body>, so you can scope additional overrides if needed.
CSS Variables
You can override Franklin's CSS variables:
:root {
--franklin-width: 480px;
--franklin-accent: #7C3AED;
--franklin-surface: #ffffff;
--franklin-border: rgba(0, 0, 0, 0.1);
--franklin-radius: 12px;
--franklin-font: 'Inter', sans-serif;
--franklin-z-index: 9999;
}API Integration
Franklin SDK expects the following API endpoints:
Chat Endpoint
POST /api/franklin/chat
Knowledge Base
GET /api/franklin/knowledge-base
Cases
GET /api/franklin/cases
GET /api/franklin/cases/:id/messages
See the API documentation for full details.
TypeScript
The SDK is fully typed. Import types as needed:
import type {
FranklinHelpCenterProps,
FranklinHelpCenterHandle,
FranklinThemeConfig,
FranklinContextPayload,
Article,
Category,
Case,
Message
} from "@franklin/sdk-react";License
Proprietary - Franklin Platform