Build your own chat interface with complete control over HTML, CSS, and behavior. You provide the markup and styling — cStar binds everything automatically via data-cstar-* attributes.

Overview

Custom Mode gives you a lightweight embed (~9KB gzipped) that connects your HTML to cStar's chat backend. Unlike the prebuilt widget, custom mode reads data-cstar-* attributes from your HTML and wires up authentication, messaging, real-time updates, file attachments, and view switching.

cStar switches to custom mode when it sees data-cstar-launcher or data-cstar-panel on the page. No flag, no config.

For programmatic control via npm instead, see @cstar.help/js, @cstar.help/react, and @cstar.help/svelte.

Want a flat reference? All data-cstar-* Attributes is the same content, condensed into Cmd+F-friendly tables.

Installation

<script src="https://www.cstar.help/cstar.js?team=YOUR_TEAM_SLUG"></script>

Replace YOUR_TEAM_SLUG with the value in Settings → Team → Install.

The script scans the page for data-cstar-* attributes and binds them automatically. New attributes added after load are picked up via a MutationObserver — no rebind call needed.

Action Triggers

Add to any clickable element. cStar attaches a click handler.

Form Inputs

Add to <input>, <textarea>, or <form> elements.

Live Content

cStar updates these elements automatically.

View Switching

Define mutually exclusive views. Only the active view is visible.

<div data-cstar-view="auth"><!-- login/signup forms --></div>
<div data-cstar-view="conversations"><!-- conversation list --></div>
<div data-cstar-view="messages"><!-- active conversation --></div>
<div data-cstar-view="new"><!-- new-conversation form --></div>
<div data-cstar-view="offline"><!-- offline fallback --></div>

Combine with auth-form state:

<div data-cstar-view="auth" data-cstar-show-when="authForm:signup"><!-- signup --></div>
<div data-cstar-view="auth" data-cstar-show-when="authForm:login"><!-- login --></div>

Standalone Auth-Form Visibility

If you don't want a separate data-cstar-view="auth" wrapper, hang these on individual auth panels:

Conditional Visibility (data-cstar-show-when)

State-Driven Panels (Auto-Hidden)

Hidden by default. cStar reveals them when the state matches.

Conversation List

Define the list and its row template:

<div data-cstar-conversations>
  <template data-cstar-conversation-template>
    <div data-cstar-conversation>
      <span data-cstar-title></span>
      <span data-cstar-preview></span>
      <span data-cstar-time></span>
      <span data-cstar-unread></span>
    </div>
  </template>
</div>
<div data-cstar-empty>No conversations yet.</div>

Per-row attributes cStar populates inside the template:

Message List

Define the container plus one or two templates (one per role):

<div data-cstar-messages>
  <template data-cstar-message-template="agent">
    <div data-cstar-message>
      <img data-cstar-avatar />
      <span data-cstar-agent-name></span>
      <div data-cstar-content></div>
      <div data-cstar-attachments></div>
      <span data-cstar-time></span>
      <span data-cstar-message-status="sending"></span>
      <span data-cstar-message-status="sent"></span>
      <span data-cstar-message-status="failed"></span>
      <button data-cstar-message-retry>Retry</button>
    </div>
  </template>

  <template data-cstar-message-template="customer">
    <div data-cstar-message>
      <div data-cstar-content></div>
      <div data-cstar-attachments></div>
      <span data-cstar-time></span>
    </div>
  </template>
</div>

Per-message attributes:

JavaScript API (window.CStarChat)

The SDK is exposed globally once the module loads. Calls made before load are queued.

// Panel
CStarChat.open();
CStarChat.close();
CStarChat.toggle();
CStarChat.isOpen();

// Identity
await CStarChat.signup({ email, name, password });
await CStarChat.login({ email, password });
await CStarChat.magicLink({ email });
await CStarChat.forgotPassword({ email });
CStarChat.identify({ email, name, customer_id });
CStarChat.verifyIdentity(customer, signature, testMode);
CStarChat.logout();
CStarChat.isIdentified();
CStarChat.getCustomer();

// Conversations
await CStarChat.startConversation({ subject, message });
CStarChat.openConversation(conversationId);
CStarChat.deleteConversation(conversationId);
CStarChat.getConversations();
CStarChat.getCurrentConversation();

// Messaging
CStarChat.send('Hello!');
CStarChat.attachFile(file);
CStarChat.removeAttachment();
CStarChat.getAttachment();

// Views & Forms
CStarChat.showView('conversations'); // or 'messages' | 'auth' | 'new' | 'offline'
CStarChat.getCurrentView();
CStarChat.showAuthForm('login');     // or 'signup' | 'forgot'
CStarChat.getAuthForm();

// Drafts (for headless input handling)
CStarChat.setDraft(value);
CStarChat.setSubject(value);
CStarChat.setAuthEmail(value);
CStarChat.setAuthName(value);
CStarChat.setAuthPassword(value);

// State
CStarChat.getUnreadCount();
CStarChat.getConnectionStatus();
CStarChat.isOnline();
CStarChat.isSoundEnabled();
CStarChat.setSoundEnabled(true);
CStarChat.requestNotifications();

// Knowledge Base
await CStarChat.searchArticles('billing', 5);
await CStarChat.getArticle('api-authentication');
await CStarChat.getPopularArticles(5);
await CStarChat.getCategories();
await CStarChat.getLibraryStats();

// Lifecycle
CStarChat.refresh();
CStarChat.destroy();

Events (CStarChat.on)

CStarChat.on('ready', () => { /* widget loaded */ });
CStarChat.on('open', () => { /* panel opened */ });
CStarChat.on('close', () => { /* panel closed */ });
CStarChat.on('identify', (customer) => { /* logged in */ });
CStarChat.on('logout', () => { });
CStarChat.on('view', (viewName) => { });
CStarChat.on('connection', (status) => { /* connected | connecting | reconnecting | offline */ });
CStarChat.on('online', (isOnline) => { });
CStarChat.on('unread', (count) => { });
CStarChat.on('message', (msg) => { /* any message */ });
CStarChat.on('message:received', (msg) => { /* from agent */ });
CStarChat.on('message:sent', (msg) => { /* from customer */ });
CStarChat.on('messages', (allMessages) => { });
CStarChat.on('conversations', (allConversations) => { });
CStarChat.on('conversation:open', (conversation) => { });
CStarChat.on('typing', (isTyping) => { });
CStarChat.on('attachment:complete', (attachment) => { });
CStarChat.on('attachment:removed', () => { });
CStarChat.on('loading', (isLoading) => { });
CStarChat.on('error', (error) => { });
CStarChat.on('session:expired', () => { });

// Unsubscribe
CStarChat.off('message', handler);

Tips

1. Wrap your panel in data-cstar-panel so open/close just works.
2. Templates beat manual rendering — let the binder handle conversation rows and message bubbles.
3. data-cstar-show-when covers most state branches without writing JavaScript.
4. Keep clickable elements at least 42px tall for mobile.
5. Agent message content is markdown — render with marked or similar if you're not using the templates.
6. New DOM mounted after page load is auto-bound. No bind() call needed.