@orki/webchat-react
v0.1.0
Published
Official React + Next.js wrapper for the Orki webchat widget. Drop-in component plus a Provider/Hook for programmatic control.
Maintainers
ahmkindiReadme
@orki/webchat-react
The official React + Next.js wrapper for the Orki webchat widget. Drop-in component plus a Provider/Hook for programmatic control.
npm install @orki/webchat-react
# or
pnpm add @orki/webchat-react
# or
yarn add @orki/webchat-react- Works in Next.js (app-router and pages-router), Vite, CRA, Remix, React Router 7 — anywhere React ≥16.8 runs.
- < 3 KB gzipped. No chat UI bundled — the widget itself is loaded on demand from your Orki deployment.
- Ships ESM + CJS + TypeScript types.
- SSR-safe, StrictMode-safe.
Quick start
Get your Tenant ID, Integration ID, and script URL from your Orki dashboard's Integrations → Web → Install panel. Paste them into:
Next.js (app-router)
// app/layout.tsx
import { OrkiWebChat } from '@orki/webchat-react';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
{children}
<OrkiWebChat
tenantId={process.env.NEXT_PUBLIC_ORKI_TENANT_ID!}
integrationId={process.env.NEXT_PUBLIC_ORKI_INTEGRATION_ID!}
scriptUrl={process.env.NEXT_PUBLIC_ORKI_SCRIPT_URL!}
/>
</body>
</html>
);
}Next.js (pages-router)
// pages/_app.tsx
import type { AppProps } from 'next/app';
import { OrkiWebChat } from '@orki/webchat-react';
export default function App({ Component, pageProps }: AppProps) {
return (
<>
<Component {...pageProps} />
<OrkiWebChat
tenantId={process.env.NEXT_PUBLIC_ORKI_TENANT_ID!}
integrationId={process.env.NEXT_PUBLIC_ORKI_INTEGRATION_ID!}
scriptUrl={process.env.NEXT_PUBLIC_ORKI_SCRIPT_URL!}
/>
</>
);
}Vite / CRA / generic React
import { OrkiWebChat } from '@orki/webchat-react';
function App() {
return (
<>
<YourApp />
<OrkiWebChat
tenantId="..."
integrationId="..."
scriptUrl="https://app.orki.ai/webchat.js"
/>
</>
);
}Programmatic control
If you want to open the chat from a "Talk to us" button, listen for new messages for analytics, or defer loading until the user accepts cookies, use the Provider + useOrkiWebChat() hook.
import { OrkiWebChatProvider, useOrkiWebChat } from '@orki/webchat-react';
function Root() {
return (
<OrkiWebChatProvider
tenantId="..."
integrationId="..."
scriptUrl="https://app.orki.ai/webchat.js"
>
<App />
</OrkiWebChatProvider>
);
}
function ContactButton() {
const { open, isReady } = useOrkiWebChat();
return (
<button onClick={open} disabled={!isReady}>
Chat with us
</button>
);
}
function AnalyticsBridge() {
const { on } = useOrkiWebChat();
useEffect(
() => on('message', ({ unreadCount }) => analytics.track('chat_message', { unreadCount })),
[on],
);
return null;
}Deferred loading (cookie consent)
<OrkiWebChatProvider
tenantId="..."
integrationId="..."
scriptUrl="https://app.orki.ai/webchat.js"
autoLoad={false}
>
<App />
</OrkiWebChatProvider>;
// ... once the user accepts cookies:
function ConsentBanner() {
const { load } = useOrkiWebChat();
return <button onClick={load}>Accept and continue</button>;
}API
<OrkiWebChat> (drop-in component)
| Prop | Type | Required | Description |
| --------------- | -------- | -------- | ---------------------------------------------------------------------------------------------- |
| tenantId | string | yes | Your Orki tenant ID (UUID). |
| integrationId | string | yes | Your web-integration ID (UUID). |
| scriptUrl | string | yes | Where webchat.js is hosted by your Orki deployment. |
| language | string | no | ISO 639-1 (e.g. "en", "ar"). |
| apiBaseUrl | string | no | Defaults to the same origin as scriptUrl. Override only if your API gateway is on a different host. |
<OrkiWebChatProvider>
Same props as <OrkiWebChat>, plus:
| Prop | Type | Default | Description |
| ---------- | --------- | ------- | ------------------------------------------------------------------------ |
| autoLoad | boolean | true | Inject the embed script on mount. Set false to defer until load(). |
| children | ReactNode | — | Your app tree. |
useOrkiWebChat()
const { isReady, load, open, close, toggle, setLanguage, on } = useOrkiWebChat();| Method | Signature | Description |
| ------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| isReady | boolean | true once the embed has mounted in the DOM. |
| load() | () => void | Injects the embed script. No-op if autoLoad already loaded it. |
| open() | () => void | Opens the chat panel. |
| close() | () => void | Closes the chat panel. |
| toggle() | () => void | Opens if closed, closes if open. |
| setLanguage() | (lang: string) => void | Switches the chat language (re-mounts the iframe). |
| on() | (event, handler) => unsubscribe | Subscribe to 'ready' \| 'opened' \| 'closed' \| 'message'. Returns an unsubscribe function. |
Content Security Policy
If your site uses CSP, allow the host serving webchat.js:
script-src ... https://YOUR-ORKI-HOST;
connect-src ... https://YOUR-ORKI-HOST;
frame-src ... https://YOUR-ORKI-HOST;License
MIT © Orki