React
Install and launch the Cossistant support widget in React.
Quick start with shadcn registry
bunx --bun shadcn@latest add cossistantcom/cossistant/support-reactThe registry installs a React-ready <Support /> starter, the CossistantProvider, the required dependencies, the widget CSS import, and a VITE_COSSISTANT_API_KEY placeholder.
1. Add your public API key
Create or copy a browser-safe public key in Settings → Developers. See API Keys for allowed domains and test/live key behavior.
VITE_COSSISTANT_API_KEY=pk_test_xxxx2. Mount CossistantProvider
import React from "react";
import ReactDOM from "react-dom/client";
import { CossistantProvider } from "@/components/cossistant/provider";
import App from "./App";
import "./index.css";
ReactDOM.createRoot(document.getElementById("root")!).render(
<React.StrictMode>
<CossistantProvider>
<App />
</CossistantProvider>
</React.StrictMode>,
);3. Render <Support />
import { Support } from "@/components/cossistant/support";
export default function App() {
return (
<main>
<h1>You are ready to chat</h1>
<Support />
</main>
);
}Quick start with AI prompt
Paste your public key to prefill the prompt, then copy it and run it in ChatGPT, Claude, or Cursor.
Manual package install
1. Install the package
pnpm add @cossistant/react
2. Add your public API key
VITE_COSSISTANT_API_KEY=pk_test_xxxxThe SDK can read VITE_COSSISTANT_API_KEY,
NEXT_PUBLIC_COSSISTANT_API_KEY, or COSSISTANT_API_KEY only when your
bundler exposes that value to browser code. Vite and Next.js expose the
first two by convention. For every other bundler, prefer an explicit
publicKey. Public keys are designed for browser use; never expose a
private key.
3. Add SupportProvider
import React from "react";
import ReactDOM from "react-dom/client";
import { SupportProvider } from "@cossistant/react";
import App from "./App";
import "./index.css";
ReactDOM.createRoot(document.getElementById("root")!).render(
<React.StrictMode>
<SupportProvider>
<App />
</SupportProvider>
</React.StrictMode>,
);If your framework does not support automatic env variable detection,
pass publicKey directly:
<SupportProvider publicKey={import.meta.env.VITE_COSSISTANT_API_KEY}>.
4. Import styles
The widget does not inject styles automatically. Import one CSS entrypoint at the app root.
Use support.css when your app already runs Tailwind CSS v4. Use styles.css everywhere else.
Both entrypoints share the same widget theme behavior. If your app already exposes standard shadcn-style tokens, the widget will usually pick up colors, radius, fonts, and dark mode automatically. No extra theme mapping is needed to start.
import React from "react";
import ReactDOM from "react-dom/client";
import { SupportProvider } from "@cossistant/react";
import "@cossistant/react/styles.css";
import App from "./App";
import "./index.css";
ReactDOM.createRoot(document.getElementById("root")!).render(
<React.StrictMode>
<SupportProvider>
<App />
</SupportProvider>
</React.StrictMode>,
);5. Render the widget
import { LazySupport } from "@cossistant/react/lazy-support";
import { Suspense } from "react";
export default function App() {
return (
<main>
<h1>You are ready to chat</h1>
<Suspense fallback={null}>
<LazySupport />
</Suspense>
</main>
);
}LazySupport keeps the complete widget UI out of the initial application
chunk. If you control when support appears, call preloadSupport from the same
entry on hover or focus before rendering it.
6. Identify logged-in visitors (optional)
import { IdentifySupportVisitor } from "@cossistant/react/identify-visitor";
import { LazySupport } from "@cossistant/react/lazy-support";
import { Suspense } from "react";
export default function App() {
const user = {
id: "user_123",
email: "jane@acme.com",
name: "Jane Doe",
};
return (
<>
<IdentifySupportVisitor
externalId={user.id}
email={user.email}
name={user.name}
/>
<Suspense fallback={null}>
<LazySupport />
</Suspense>
</>
);
}Verify the installation
Reload the app and confirm that:
- the support trigger appears without an unstyled flash
- opening it shows the home screen or a new conversation
- the browser network panel has no
401or403response from the Cossistant API
If the trigger is missing, check that you imported exactly one CSS entrypoint.
If requests return 401, confirm the public key. If they return 403, add the
current hostname—including localhost during development—to the key's allowed
domains. See API Keys for the full checklist.
7. Display custom messages with SupportConfig defaultMessages
import { Support, SupportConfig } from "@cossistant/react";
import { type DefaultMessage, SenderType } from "@cossistant/types";
const user: { name: string | null } = {
name: "Jane Doe",
};
const defaultMessages: DefaultMessage[] = [
{
content: `Hi ${user.name ?? "there"}, anything I can help with?`,
senderType: SenderType.TEAM_MEMBER,
},
];
const quickOptions: string[] = ["How to identify a visitor?"];
export default function App() {
return (
<>
<SupportConfig
defaultMessages={defaultMessages}
quickOptions={quickOptions}
/>
<Support />
</>
);
}Next in the Support docs
- Overview for the fastest path from first render to production-ready widget.
- Change One Thing to swap the bubble or first screen without rebuilding the widget.
- Match Your Brand to set colors, radius, and dark mode.
Was this page helpful?
Open a prefilled documentation issue so the team can act on your feedback.
On this page
Quick start with shadcn registry1. Add your public API key2. MountCossistantProvider3. Render <Support />Quick start with AI promptManual package install1. Install the package2. Add your public API key3. Add SupportProvider4. Import styles5. Render the widget6. Identify logged-in visitors (optional)Verify the installation7. Display custom messages with SupportConfig defaultMessagesNext in the Support docs