@cstar.help/react

@cstar.help/react

React hooks for the cStar customer support platform. Build custom chat widgets and knowledge base UIs with type-safe, SSR-compatible hooks.

• React 18+ — hooks with automatic loading states and error handling
• Three modules — Chat (real-time messaging), Library (knowledge base), and Community (forum)
• TypeScript-first — full type definitions included
• Tiny — ~18 KB, tree-shakeable, only peer deps

Install

npm install @cstar.help/react @cstar.help/js

Chat

Wrap your app in <CStarChatProvider> and use hooks anywhere inside.

Setup

import { CStarChatProvider } from '@cstar.help/react';

function App() {
	return (
		<CStarChatProvider teamSlug="acme">
			<ChatWidget />
		</CStarChatProvider>
	);
}

Identify the Customer

import { useChat } from '@cstar.help/react';

function ChatWidget() {
	const { identify, isIdentified, isRealtimeReady, error } = useChat();

	useEffect(() => {
		identify(
			{ externalId: 'usr_123', email: '[e-mail]', timestamp: Math.floor(Date.now() / 1000) },
			hmacSignature // computed server-side
		);
	}, []);

	if (!isIdentified) return <p>Connecting...</p>;
	return <TicketList />;
}

Tickets

import { useTickets } from '@cstar.help/react';

function TicketList() {
	const { tickets, isLoading, create, refresh, hasMore } = useTickets();

	if (isLoading) return <Spinner />;

	return (
		<ul>
			{tickets.map((t) => (
				<li key={t.id}>{t.subject}</li>
			))}
		</ul>
	);
}

Messages + Typing Indicators

import { useMessages, useTyping } from '@cstar.help/react';

function ChatWindow({ ticketId }) {
	const { messages, isLoading, send } = useMessages(ticketId);
	const { typingAgents, sendTyping } = useTyping(ticketId);
	const [text, setText] = useState('');

	const handleSend = async () => {
		await send(text); // optimistic — appears instantly
		setText('');
	};

	return (
		<>
			{messages.map((msg) => (
				<div key={msg.id}>{msg.content}</div>
			))}
			{typingAgents.map((a) => (
				<p key={a.agentId}>{a.agentName} is typing...</p>
			))}
			<input
				value={text}
				onChange={(e) => {
					setText(e.target.value);
					sendTyping(e.target.value.length > 0);
				}}
				onKeyDown={(e) => e.key === 'Enter' && handleSend()}
			/>
		</>
	);
}

Knowledge Base

Wrap in <CStarLibraryProvider> for public knowledge base access — no auth required.

Setup

import { CStarLibraryProvider } from '@cstar.help/react';

function App() {
	return (
		<CStarLibraryProvider teamSlug="acme">
			<HelpCenter />
		</CStarLibraryProvider>
	);
}

Categories + Articles

import { useCategories, useArticles, useArticle } from '@cstar.help/react';

function HelpCenter() {
	const { categories, isLoading: catsLoading } = useCategories();
	const { articles, isLoading: artsLoading } = useArticles({ categorySlug: 'getting-started' });

	return (
		<>
			<nav>
				{categories.map((cat) => (
					<a key={cat.id}>{cat.name}</a>
				))}
			</nav>
			<ul>
				{articles.map((a) => (
					<li key={a.id}>{a.title}</li>
				))}
			</ul>
		</>
	);
}

// Single article by slug
function ArticlePage({ slug }) {
	const { article, isLoading, error } = useArticle(slug);
	if (isLoading) return <Spinner />;
	if (!article) return <NotFound />;
	return <h1>{article.title}</h1>;
}

Search with Debouncing

import { useArticleSearch } from '@cstar.help/react';

function SearchBar() {
	const [query, setQuery] = useState('');
	const { results, totalCount, isLoading } = useArticleSearch(query); // 300ms debounce built-in

	return (
		<>
			<input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="Search..." />
			{isLoading && <Spinner />}
			{results.map((a) => (
				<a key={a.id} href={`/articles/${a.slug}`}>
					{a.title}
				</a>
			))}
		</>
	);
}

Community

Wrap in <CStarCommunityProvider> for public community forum access — no auth required.

Setup

import { CStarCommunityProvider } from '@cstar.help/react';

function App() {
	return (
		<CStarCommunityProvider teamSlug="acme">
			<CommunityForum />
		</CStarCommunityProvider>
	);
}

Topics + Posts

import { useTopics, usePosts, usePost } from '@cstar.help/react';

function CommunityForum() {
	const { topics, isLoading: topicsLoading } = useTopics();
	const { posts, count, isLoading: postsLoading } = usePosts({ sort: 'votes' });

	return (
		<>
			<nav>
				{topics.map((topic) => (
					<a key={topic.id}>{topic.name}</a>
				))}
			</nav>
			<p>{count} posts</p>
			<ul>
				{posts.map((post) => (
					<li key={post.id}>
						{post.title} — {post.voteCount} votes
					</li>
				))}
			</ul>
		</>
	);
}

// Single post with comments
function PostPage({ slug }) {
	const { data, isLoading, error } = usePost(slug);
	if (isLoading) return <Spinner />;
	if (!data) return <NotFound />;
	return (
		<>
			<h1>{data.post.title}</h1>
			{data.comments.map((c) => (
				<p key={c.id}>{c.body}</p>
			))}
		</>
	);
}

Search

import { useCommunitySearch } from '@cstar.help/react';

function CommunitySearch() {
	const { results, isLoading, search } = useCommunitySearch();

	return (
		<>
			<input onChange={(e) => search(e.target.value)} placeholder="Search posts..." />
			{results?.data.map((post) => (
				<a key={post.id}>{post.title}</a>
			))}
		</>
	);
}

API Reference

Chat Hooks

Hook	Returns	Description
useChat()	{ identify, disconnect, isIdentified, isRealtimeReady, error }	Identity verification and connection state
useTickets()	{ tickets, isLoading, error, hasMore, refresh, create }	List and create tickets
useMessages(ticketId)	{ messages, isLoading, error, send, refresh }	Messages with real-time updates and optimistic send
useTyping(ticketId)	{ typingAgents, sendTyping }	Agent typing indicators with auto-clear (4s timeout)

Library Hooks

Hook	Returns	Description
useCategories()	{ categories, isLoading, error, refresh }	Knowledge base categories
useArticles(params?)	{ articles, isLoading, error, refresh }	Articles, optionally filtered by category
useArticle(slug)	{ article, isLoading, error, refresh }	Single article by slug
useArticleSearch(query)	{ results, totalCount, isLoading, error }	Search with 300ms debounce

Community Hooks

Hook	Returns	Description
useTopics()	{ topics, isLoading, error, refresh }	Community discussion topics
usePosts(params?)	{ posts, count, isLoading, error, refresh }	Posts with optional filters (topicSlug, status, sort)
usePost(slug)	{ data, isLoading, error, refresh }	Single post with comments
useCommunitySearch()	{ results, isLoading, error, search }	On-demand search across posts

Context Accessors

Function	Returns	Description
useChatClient()	ChatClient	Raw client from nearest CStarChatProvider
useLibraryClient()	LibraryClient	Raw client from nearest CStarLibraryProvider
useCommunityClient()	CommunityClient	Raw client from nearest CStarCommunityProvider

Using with Next.js App Router (RSC)

The dashboard provider (CStarDashboardProvider) wraps a CStarClient, which is a class instance — and React Server Components can't serialize class instances across the server/client boundary. The provider therefore takes one of two prop shapes:

Recommended — pass a plain config object. The provider builds (and disposes) the client inside the 'use client' boundary, so nothing class-shaped crosses the RSC boundary:

// app/providers.tsx
'use client';
import { CStarDashboardProvider } from '@cstar.help/react';

export function Providers({ children }: { children: React.ReactNode }) {
	return (
		<CStarDashboardProvider
			config={{
				apiKey: process.env.NEXT_PUBLIC_CSTAR_PUBLISHABLE_KEY!,
				teamId: process.env.NEXT_PUBLIC_CSTAR_TEAM_ID!
			}}
		>
			{children}
		</CStarDashboardProvider>
	);
}

Use the apiKey field for a publishable key (pk_live_* / pk_test_*), NOT a secret key — the bundle ships to the browser. For server-only flows (an admin route handler, a server action), construct CStarClient with the secret key inline; never thread it into a provider.

Legacy — pass a pre-built client (deprecated). If you already have a client instance you want to share, the client prop still works, but you have to construct it inside 'use client' and you take on responsibility for tearing down the realtime subscription:

'use client';
import { useMemo } from 'react';
import { CStarClient } from '@cstar.help/js';
import { CStarDashboardProvider } from '@cstar.help/react';

export function Providers({ children }) {
	const client = useMemo(
		() =>
			new CStarClient({
				apiKey: process.env.NEXT_PUBLIC_CSTAR_PUBLISHABLE_KEY!,
				teamId: process.env.NEXT_PUBLIC_CSTAR_TEAM_ID!
			}),
		[]
	);
	return <CStarDashboardProvider client={client}>{children}</CStarDashboardProvider>;
}

Either way, mark the file 'use client'. Server components can sit above the provider in the tree — only the provider boundary needs to be a client component.

Requirements

• React 18+
• @cstar.help/js 0.1.0+
• Node.js 18+ (for SSR)

License

MIT